How to install

There basically three different methodologies for the installation. You should choose the one, which is the most appropriate solution concerning your skills and your usage:

The recommended installation

We recommend to use anaconda for installing python and psyplot (see Installation using conda). If you however already have python installed on your system, you can also use pip (see Installation using pip).

The developer installation

Install it from source (see Installation from source)

Installation using conda

We highly recommend to use conda for installing psyplot. After having downloaded the installer from anaconda or miniconda, you can install psyplot and the optional plugins (see Optional dependencies) via:

$ conda install -c conda-forge psy-view psy-reg

If you only want to install the core, i.e. the raw framework, run:

$ conda install -c conda-forge psyplot

If you want to be able to read GeoTiff Raster files, you will need to have gdal installed:

$ conda install gdal

Please also visit the xarray installation notes for more informations on how to best configure the xarray package for your needs.

Installation using pip

If you do not want to use conda for managing your python packages, you can also use the python package manager pip and install via:

$ pip install psyplot

However to be on the safe side, make sure you have the Dependencies installed.

Installation from source

To install it from source, make sure you have the Dependencies installed, clone the github repository via:

git clone

and install it via:

python install


Required dependencies

Psyplot supports officially python 3.6 and 3.7. Previous versions are also available for python 2.7. Furthermore the package is built upon multiple other packages, mainly

  • xarray>=0.8: Is used for the data management in the psyplot package

  • matplotlib>=1.4.3<3.1: The python visualiation package

  • PyYAML: Needed for the configuration of psyplot

  • docrep: A package for efficient documentation processing for large APIs

  • funcargparse: A package to create command line parsers from function docstrings

Optional dependencies

We furthermore recommend to use

  • psyplot-gui: A graphical user interface to psyplot

  • psy-view: An ncview-like interface based on psyplot and psy-maps

  • psy-simple: A psyplot plugin to make simple plots

  • psy-maps: A psyplot plugin for visualizing data on a map

  • psy-reg: A psyplot plugin for visualizing fits to your data

  • cdo: The python bindings for cdos (see also the cdo example)

Running the tests

We us pytest to run our tests. So you can either run clone out the github repository and run:

$ python test

or install pytest by yourself and run:

$ py.test

To also test the plugin functionality, install the psyplot_test module in tests/test_plugin via:

$ cd tests/test_plugin && python install

and run the tests via one of the above mentioned commands.

Building the docs

To build the docs, check out the github repository and install the requirements in 'docs/environment.yml'. The easiest way to do this is via anaconda by typing:

$ conda env create -f docs/environment.yml
$ source activate psyplot_docs

Then build the docs via:

$ cd docs
$ make html


The building of the docs always preprocesses the examples. You might want to disable that by setting process_examples = False. Otherwise please note that the examples are written as python3 notebooks, hence you may have to install a python3 kernel through ipykernel. Just create a new environment 'py37' and install it via:

conda create -n py37 python=3.7
source activate py37
conda install notebook ipykernel
ipython kernel install --user

You then have to install the necessary modules for each of the examples in the new 'py37' environment.


The uninstallation depends on the system you used to install psyplot. Either you did it via conda (see Uninstallation via conda), via pip or from the source files (see Uninstallation via pip).

Anyway, if you may want to remove the psyplot configuration files. If you did not specify anything else (see psyplot.config.rcsetup.psyplot_fname()), the configuration files for psyplot are located in the user home directory. Under linux and OSX, this is $HOME/.config/psyplot. On other platforms it is in the .psyplot directory in the user home.

Uninstallation via conda

If you installed psyplot via conda, simply run:

conda remove psyplot

or, if you installed it into an own conda environment, remove the environment via:

conda env remove -n <environment-name>

Uninstallation via pip

Uninstalling via pip simply goes via:

pip uninstall psyplot

Note, however, that you should use conda if you also installed it via conda.