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 [-h] [-V] [-aV] [-i] [-lp] [-lpm] [-lds] [-lps]
               [-n [variable_name ...]] [-d dim,val1[,val2[,...]]
               [dim,val1[,val2[,...]] ...]]
               [-pm {'combined', 'fldmean', 'plot2d', 'vector', 'lineplot', 'mapvector', 'violinplot', 'barplot', 'mapcombined', 'mapplot', 'density'}]
               [-o str or list of str] [-p str] [-engine str]
               [-fmt FILENAME_OR_YAML] [-t] [-rc RC_FILE] [-e str]
               [--enable-post] [-sns str] [-op str] [-cd str]
               [-chname [project-variable,variable-to-use ...]] [-preset str]
               [--decoder FILENAME_OR_YAML]
               [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: combined, fldmean, plot2d, vector, lineplot, mapvector, violinplot, barplot, mapcombined, mapplot, density

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

YAML-formatted formatoption (e.g. ‘cmap: Reds’), or the path to a yaml ('.yml' or '.yaml'), JSON ('.json') 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()).


YAML-formatted decoder options (e.g. ‘x: x-coordinate’), or the path to a yaml ('.yml' or '.yaml'), JSON ('.json') or pickle file defining a dictionary of formatoption that is applied to the data visualized by the chosen plot_method

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

-i, --info

Show grid information on the specified variables.

-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