Skip to content

Latest commit

 

History

History
312 lines (223 loc) · 11 KB

INSTALL.rst

File metadata and controls

312 lines (223 loc) · 11 KB
Raw

Installation Guide

Note

If you wish to contribute to the project, it's recommended you :ref:`install the latest development version<install_from_source>`.

Contents

Installing an official release

Matplotlib and its dependencies are available as wheel packages for macOS, Windows and Linux distributions:

python -m pip install -U pip
python -m pip install -U matplotlib

If this command results in Matplotlib being compiled from source and there's trouble with the compilation, you can add --prefer-binary to select the newest version of Matplotlib for which there is a precompiled wheel for your OS and Python.

Note

The following backends work out of the box: Agg, ps, pdf, svg

Python is typically shipped with tk bindings which are used by TkAgg.

For support of other GUI frameworks, LaTeX rendering, saving animations and a larger selection of file formats, you need to install :ref:`additional dependencies <install_requirements>`.

Although not required, we suggest also installing IPython for interactive use. To easily install a complete Scientific Python stack, see :ref:`install_scipy_dists` below.

Test data

The wheels (:file:`*.whl`) on the PyPI download page do not contain test data or example code.

If you want to try the many demos that come in the Matplotlib source distribution, download the :file:`*.tar.gz` file and look in the :file:`examples` subdirectory.

To run the test suite:

Third-party distributions of Matplotlib

Scientific Python Distributions

Anaconda and ActiveState are excellent choices that "just work" out of the box for Windows, macOS and common Linux platforms. WinPython is an option for Windows users. All of these distributions include Matplotlib and lots of other useful (data) science tools.

Linux: using your package manager

If you are on Linux, you might prefer to use your package manager. Matplotlib is packaged for almost every major Linux distribution.

  • Debian / Ubuntu: sudo apt-get install python3-matplotlib
  • Fedora: sudo dnf install python3-matplotlib
  • Red Hat: sudo yum install python3-matplotlib
  • Arch: sudo pacman -S python-matplotlib

Installing from source

If you are interested in contributing to Matplotlib development, running the latest source code, or just like to build everything yourself, it is not difficult to build Matplotlib from source.

A C compiler is required. Typically, on Linux, you will need gcc, which should be installed using your distribution's package manager; on macOS, you will need xcode; on Windows, you will need Visual Studio 2015 or later.

The easiest way to get the latest development version to start contributing is to go to the git repository and run:

git clone https://github.com/matplotlib/matplotlib.git

or:

git clone [email protected]:matplotlib/matplotlib.git

If you're developing, it's better to do it in editable mode. The reason why is that pytest's test discovery only works for Matplotlib if installation is done this way. Also, editable mode allows your code changes to be instantly propagated to your library code without reinstalling (though you will have to restart your python process / kernel):

cd matplotlib
python -m pip install -e .

If you're not developing, it can be installed from the source directory with a simple (just replace the last step):

python -m pip install .

To run the tests you will need to install some additional dependencies:

python -m pip install -r requirements/dev/dev-requirements.txt

Then, if you want to update your Matplotlib at any time, just do:

git pull

When you run git pull, if the output shows that only Python files have been updated, you are all set. If C files have changed, you need to run pip install -e . again to compile them.

There is more information on :ref:`using git <using-git>` in the developer docs.

Warning

The following instructions in this section are for very custom installations of Matplotlib. Proceed with caution because these instructions may result in your build producing unexpected behavior and/or causing local testing to fail.

If you would like to build from a tarball, grab the latest tar.gz release file from the PyPI files page.

We provide a setup.cfg file which you can use to customize the build process. For example, which default backend to use, whether some of the optional libraries that Matplotlib ships with are installed, and so on. This file will be particularly useful to those packaging Matplotlib.

Dependencies

Matplotlib will automatically install dependencies when you install with pip, so this section is mostly for your reference.

Matplotlib requires the following dependencies:

Optionally, you can also install a number of packages to enable better user interface toolkits. See :ref:`what-is-a-backend` for more details on the optional Matplotlib backends and the capabilities they provide.

  • Tk (>= 8.3, != 8.6.0 or 8.6.1): for the Tk-based backends.
  • PyQt4 (>= 4.6) or PySide (>= 1.0.3) [1]: for the Qt4-based backends.
  • PyQt5 or PySide2: for the Qt5-based backends.
  • PyGObject: for the GTK3-based backends [2].
  • wxPython (>= 4) [3]: for the wx-based backends.
  • pycairo (>= 1.11.0) or cairocffi (>= 0.8): for the GTK3 and/or cairo-based backends.
  • Tornado: for the WebAgg backend.
[1]PySide cannot be pip-installed on Linux (but can be conda-installed).
[2]If using pip (and not conda), PyGObject must be built from source; see https://pygobject.readthedocs.io/en/latest/devguide/dev_environ.html.
[3]If using pip (and not conda) on Linux, wxPython wheels must be manually downloaded from https://wxpython.org/pages/downloads/.

For better support of animation output format and image file formats, LaTeX, etc., you can install the following:

FreeType and Qhull

Matplotlib depends on FreeType (>= 2.3), a font rendering library, and on Qhull (>= 2015.2), a library for computing triangulations. By default (except on AIX) Matplotlib downloads and builds its own copy of FreeType (this is necessary to run the test suite, because different versions of FreeType rasterize characters differently), and uses its own copy of Qhull.

To force Matplotlib to use a copy of FreeType or Qhull already installed in your system, create a :file:`setup.cfg` file with the following contents:

[libs]
system_freetype = true
system_qhull = true

before running python -m pip install ..

In this case, you need to install the FreeType and Qhull library and headers. This can be achieved using a package manager, e.g. for FreeType:

# Pick ONE of the following:
sudo apt install libfreetype6-dev  # Debian/Ubuntu
sudo dnf install freetype-devel  # Fedora
brew install freetype  # macOS with Homebrew
conda install freetype  # conda, any OS

(adapt accordingly for Qhull).

On Linux and macOS, it is also recommended to install pkg-config, a helper tool for locating FreeType:

# Pick ONE of the following:
sudo apt install pkg-config  # Debian/Ubuntu
sudo dnf install pkgconf  # Fedora
brew install pkg-config  # macOS with Homebrew
conda install pkg-config  # conda
# Or point the PKG_CONFIG environment variable to the path to pkg-config:
export PKG_CONFIG=...

If not using pkg-config (in particular on Windows), you may need to set the include path (to the library headers) and link path (to the libraries) explicitly, if they are not in standard locations. This can be done using standard environment variables -- on Linux and OSX:

export CFLAGS='-I/directory/containing/ft2build.h'
export LDFLAGS='-L/directory/containing/libfreetype.so'

and on Windows:

set CL=/IC:\directory\containing\ft2build.h
set LINK=/LIBPATH:C:\directory\containing\freetype.lib

Note

Matplotlib always uses its own copies of the following libraries:

  • Agg: the Anti-Grain Geometry C++ rendering engine;
  • ttconv: a TrueType font utility.

If you go this route but need to reset and rebuild to change your settings, remember to clear your artifacts before re-building:

git clean -xfd

Building on Windows

Compiling Matplotlib (or any other extension module, for that matter) requires Visual Studio 2015 or later.

If you are building your own Matplotlib wheels (or sdists), note that any DLLs that you copy into the source tree will be packaged too.

Conda packages

The conda packaging scripts for Matplotlib are available at https://github.com/conda-forge/matplotlib-feedstock.