Command line usage

The psyplot.__main__ module defines a simple parser to parse commands from the command line to make a plot of data in a netCDF file. Note that the arguments change slightly if you have the psyplot-gui module installed (see psyplot-gui documentation).

It can be run from the command line via:

python -m psyplot [options] [arguments]

or simply:

psyplot [options] [arguments]

Load a dataset, make the plot and save the result to a file

usage: psyplot
       [-n [variable_name [variable_name ...]]]
       [-d dim,val1[,val2[,...]]
       [-pm {'violinplot', 'mapcombined', 'lineplot', 'density', 'mapvector', 'vector', 'plot2d', 'fldmean', 'combined', 'barplot', 'mapplot'}]
       [-o str or list of str]
       [-p str]
       [-engine str]
       [-fmt FILENAME]
       [-rc RC_FILE]
       [-e str]
       [-sns str]
       [-op str]
       [-cd str]
       [-chname [project-variable,variable-to-use [project-variable,variable-to-use ...]]]
       [-preset str]
       [str [str ...]]

Positional Arguments


Either the filenames to show, or, if the project parameter is set, the a list of ,-separated filenames to make a mapping from the original filename to a new one

Default: []

Named Arguments

-n, --name

The variable names to plot if the output parameter is set

Default: []

-d, --dims

A mapping from coordinate names to integers if the project is not given

-pm, --plot-method

Possible choices: violinplot, mapcombined, lineplot, density, mapvector, vector, plot2d, fldmean, combined, barplot, mapplot

The name of the plot_method to use

-p, --project

If set, the project located at the given file name is loaded


The engine to use for opening the dataset (see

-fmt, --formatoptions

The path to a yaml ('.yml' or '.yaml') or pickle file defining a dictionary of formatoption that is applied to the data visualized by the chosen plot_method

-rc, --rc-file

The path to a yaml configuration file that can be used to update the rcParams

-e, --encoding

The encoding to use for loading the project. If None, it is automatically determined by pickle. Note: Set this to 'latin1' if using a project created with python2 on python3.


Enable the post processing formatoption. If True/set, post processing scripts are enabled in the given project. Only set this if you are sure that you can trust the given project file because it may be a security vulnerability.

Default: False

-sns, --seaborn-style

The name of the style of the seaborn package that can be used for the seaborn.set_style() function

-cd, --concat-dim

The concatenation dimension if multiple files in fnames are provided


A mapping from variable names in the project to variable names in the datasets that should be used instead. Variable names should be separated by a comma.

Default: {}


The filename or identifier of a preset. If the given preset is the path to an existing yaml file, it will be loaded. Otherwise we look up the preset in the psyplot configuration directory (see get_configdir()).

Info options

Options that print informations and quit afterwards

-V, --version

show program’s version number and exit

-aV, --all-versions

Print the versions of all plugins and requirements and exit

-lp, --list-plugins

Print the names of the plugins and exit

-lpm, --list-plot-methods

List the available plot methods and what they do

-lds, --list-datasets

List the used dataset names in the given project.

-lps, --list-presets

Print available presets and exit

Output options

Options that only have an effect if the -o option is set.

-o, --output

If set, the data is loaded and the figures are saved to the specified filename and now graphical user interface is shown

-t, --tight

If True/set, it is tried to figure out the tight bbox of the figure and adjust the paper size of the output to it

Default: False

-op, --output-project

The name of a project file to save the project to


Here are some examples on how to use psyplot from the command line.

Plot the variable 't2m' in a netCDF file '' and save the plot to 'plot.pdf':

$ psyplot -n t2m -pm mapplot -o test.pdf

Create two plots for 't2m' with the first and second timestep on the second vertical level:

$ psyplot -n t2m  -pm mapplot -o test.pdf -d t,0,1 z,1

If you have save a project using the psyplot.project.Project.save_project() method into a file named 'project.pkl', you can replot this via:

$ psyplot -p project.pkl -o test.pdf

If you use a different dataset than the one you used in the project (e.g. ''), you can replace it via:

$ psyplot -p project.pkl -o test.pdf

or explicitly via:

$ psyplot, -p project.pkl -o test.pdf

You can also load formatoptions from a configuration file, e.g.:

$ echo 'title: my title' > fmt.yaml
$ psyplot -n t2m  -pm mapplot -fmt fmt.yaml -o test.pdf