Advanced Installation Instructions¶
This document provides details on things you need to know to install and manage your own scientific Python + SunPy installation. If you have never installed or used scientific Python we recommend that you follow the Anaconda installation instructions.
Alternative Scientific Python Installation Instructions¶
There are many alternatives to Anaconda as a way of installing a scientific Python environment, there are various other platform specific ways to install scientific Python:
Installing SunPy on top of an existing Scientific Python Environment¶
These instructions assume you have a scientific Python distribution with access
pip command installed.
You will need a compiler suite and the development headers for Python and Numpy in order to build SunPy. On Linux, using the package manager for your distribution will usually be the easiest route, while on MacOS X you will need the XCode command line tools.
The instructions for building Numpy from source are also a good resource for setting up your environment to build Python packages.
If you are using MacOS X, you will need to the XCode command line tools. One way to get them is to install XCode. If you are using OS X 10.7 (Lion) or later, you must also explicitly install the command line tools. You can do this by opening the XCode application, going to Preferences, then Downloads, and then under Components, click on the Install button to the right of Command Line Tools. Alternatively, on 10.7 (Lion) or later, you do not need to install XCode, you can download just the command line tools from the Apple developer site (requires an Apple developer account).
SunPy consists of many submodules that each have their own requirements.
You do not need to fulfil all the requirements if you only intend on using
parts of SunPy. It is however strongly recommended to have all the
dependencies installed (with the potential exception of
SunPy has the following strict requirements:
SunPy also depends on other packages for optional features. However, note that these only need to be installed if those particular features are needed. SunPy will import even if these dependencies are not installed.
- Matplotlib [Highly Recommended] 1.3.0 or later:
- pandas 0.10 or later: For
- sqlalchemy: For the
- suds-jurko: For
- beautifulsoup4: For
- requests: For the
- wcsaxes: For
- glymur 0.5.9 or later: To enable reading of JPEG2000 files. Glymur requires the installation of the OpenJPEG C library.
- pytest: To run tests.
The packages that will be installed as dependencies by default and are the ones
required to import the core datatypes
spectra. These are the strict requirements and the following optional
There are multiple options depending on how many optional dependencies you want to install:
To install SunPy with
pip including optional dependencies (recommended), simply run:
pip install sunpy[all]
To install SunPy with no optional dependencies:
pip install sunpy
To install SunPy with net-based dependencies (suds and beautifulsoup):
pip install sunpy[net]
To install SunPy with database dependencies (sqlalchemy):
pip install sunpy[database]
Users of the Anaconda python distribution should follow the instructions for Anaconda python distribution.
You will need a C compiler (e.g.
clang) to be installed.
If you get a
PermissionError this means that you do not have the
required administrative access to install new packages to your Python
installation. In this case you may consider using the
to install the package into your home directory. You can read more about
how to do this in the pip documentation.
Alternatively, if you intend to do development on other software that uses SunPy, such as an affiliated package, consider installing SunPy into a virtualenv.
Do not install SunPy or other third-party packages using
unless you are fully aware of the risks.
The easiest way to test your installed version of SunPy is running
correctly is to use the
import sunpy sunpy.self_test(online=False)
which will run many of the SunPy tests.
The tests should run and print out any failures, which you can report at the SunPy issue tracker.
Installing the Development Version of SunPy¶
The latest (bleeding-edge) development version of SunPy can be cloned from github using this command:
git clone git://github.com/sunpy/sunpy.git
If you wish to participate in the development of SunPy, see Developer Documentation. This document covers only the basics necessary to install SunPy.
Once inside the source directory that has been clone from GitHub you can install SunPy using:
python setup.py install
This command will need access to system folders append
--user to install
SunPy into your home directory.
If you get an error mentioning that you do not have the correct permissions to
install SunPy into the default
site-packages directory, you should try
pip install sunpy --user
which will install into a default directory in your home directory.
Building the documentation is in general not necessary unless you are writing new documentation or do not have internet access, because the latest (and archive) versions of SunPy’s documentation are available at docs.sunpy.org .
Building the documentation requires the SunPy source code and some additional packages:
Sphinx also requires a reasonably modern LaTeX installation to render equations. Per the Sphinx documentation, for the TexLive distribution the following packages are required to be installed:
For other LaTeX distributions your mileage may vary. To build the PDF
documentation using LaTeX, the
fonts-extra TexLive package or the
inconsolata CTAN package are also required.
There are two ways to build the SunPy documentation. The most straightforward way is to execute the command (from the sunpy source directory):
python setup.py build_sphinx -lo
The documentation will be built in the
doc/build/html directory, and can
be read by pointing a web browser to
The LaTeX documentation can be generated by using the command:
python setup.py build_sphinx -b latex
The LaTeX file
SunPy.tex will be created in the
directory, and can be compiled using
The above method builds the API documentation from the source code.