APLpy documentation

APLpy (the Astronomical Plotting Library in Python - pronounced apple pie) is a Python package module aimed at producing publication-quality plots of astronomical imaging data, and has been around since 2009.

Since APLpy 2.0, APLpy relies on Astropy’s WCSAxes package to draw the coordinate axes and grids, which in turn uses Matplotlib to do the rendering. This is a big change compared to previous versions of APLpy, which handled the drawing of the coordinate axes and grids directly. For information about backward-compatibility, see the Backward-compatibility notes.

Note that APLpy 2.x is only compatible with Python 3.5 and later.

If you use APLpy for a publication, please consider citing it as described in the CITATION file.

Should you use APLpy?

The WCSAxes package in Astropy can be used without APLpy to produce plots of astronomical images. It provides a programmatic interface that is conceptually very close to Matplotlib, and can be used to make plots that are more complex than what APLpy has historically been able to do. If you want to be able to control the appearance of your plots in detail, including for example adding overlay coordinate systems, or if you simply want a programmatic interface that is consistent with Matplotlib, then we recommend you use WCSAxes directly. If you have a FITS file and just want to make it into a plot in a couple of lines, then APLpy is the package for you.

Installing APLpy

You can install APLpy with pip using:

pip install aplpy

If you prefer to use conda, you can install APLpy with:

conda install -c astropy aplpy

Using APLpy

APLpy includes a FITSFigure class that provides a simple interface to make plots and provides easy methods for overlaying shapes, beams, adding colorbars, and overplotting regions.

Backward-compatibility notes

APLpy continues to include a FITSFigure class that provides a simpler interface and deals with the reading of FITS files and constructing WCS objects. This class uses WCSAxes behind the scenes, but provides easy methods for overlaying shapes, beams, adding colorbars, and overplotting regions. The interface of this class is intended to be backward-compatible with existing scripts that used APLpy 1.0 and earlier. If you run into issues with old scripts, please report the issues in the issue tracker.

Note however that if you have made adjustments to figures in the past using private attributes (e.g. fig._ax1), these will no longer work and this cannot be fixed in APLpy 2.x.

In any case, if you have issues with APLpy 2.x and want to continue using APLpy 1.x, you can always restrict the version of APLpy when installing it using e.g.:

pip install "aplpy<2"


conda install "aplpy<2"

If critical bugs are found in the 1.x releases and can easily be fixed, we may release new 1.x versions.



make_rgb_cube(files, output[, north]) Make an RGB data cube from a list of three FITS images.
make_rgb_image(data, output[, indices, …]) Make an RGB image from a FITS RGB cube or from three FITS files.
test([package, test_path, args, plugins, …]) Run the tests using py.test.


FITSFigure(data[, hdu, figure, subplot, …]) Create a FITSFigure instance.