Skip to content

Backport PR #19725/#19758 on branch v3.4.0-doc (Cleanup installing docs) #19781

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 26, 2021
Merged

Backport PR #19725/#19758 on branch v3.4.0-doc (Cleanup installing docs) #19781

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 47 additions & 102 deletions INSTALL.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,22 @@
==================
Installation Guide
==================
############
Installation
############

.. note::
.. toctree::
:hidden:

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

.. contents::

==============================
Installing an official release
==============================

Matplotlib and its dependencies are available as wheel packages for macOS,
Windows and Linux distributions::
Matplotlib releases are available as wheel packages for macOS, Windows and
Linux on `PyPI <https://pypi.org/project/matplotlib/>`_. Install it using
``pip``:

.. code-block:: sh

python -m pip install -U pip
python -m pip install -U matplotlib
Expand All @@ -34,114 +37,56 @@ precompiled wheel for your OS and Python.
animations and a larger selection of file formats, you can
install :ref:`optional_dependencies`.

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.

Third-party distributions of Matplotlib
=======================================

.. _install_scipy_dists:

Scientific Python Distributions
-------------------------------

`Anaconda <https://www.anaconda.com/>`_ and `ActiveState
<https://www.activestate.com/activepython/downloads>`_ are excellent
choices that "just work" out of the box for Windows, macOS and common
Linux platforms. `WinPython <https://winpython.github.io/>`_ 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
---------------------------------
=========================
Third-party distributions
=========================

If you are on Linux, you might prefer to use your package manager. Matplotlib
is packaged for almost every major Linux distribution.
Various third-parties provide Matplotlib for their environments.

* 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``

.. _install_from_source:

Installing from source
======================
Conda packages
==============
Matplotlib is available both via the *anaconda main channel*

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.
.. code-block:: sh

First you need to install the :ref:`dependencies`.
conda install matplotlib

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.
as well as via the *conda-forge community channel*

.. _xcode: https://guide.macports.org/chunked/installing.html#installing.xcode
.. code-block:: sh

The easiest way to get the latest development version to start contributing
is to go to the git `repository <https://github.com/matplotlib/matplotlib>`_
and run::
conda install -c conda-forge matplotlib

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

or::
Python distributions
====================

git clone git@github.com:matplotlib/matplotlib.git
Matplotlib is part of major Python distributions:

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)::
- `Anaconda <https://www.anaconda.com/>`_

cd matplotlib
python -m pip install -e .
- `ActiveState ActivePython
<https://www.activestate.com/activepython/downloads>`_

If you're not developing, it can be installed from the source directory with
a simple (just replace the last step)::
- `WinPython <https://winpython.github.io/>`_

python -m pip install .
Linux package manager
=====================

To run the tests you will need to install some additional dependencies::
If you are using the Python version that comes with your Linux distribution,
you can install Matplotlib via your package manager, e.g.:

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 <https://pypi.org/project/matplotlib/>`_.

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.

.. _setup.cfg: https://raw.githubusercontent.com/matplotlib/matplotlib/master/setup.cfg.template
* 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``

Building on Windows
-------------------
======================
Installing from source
======================
See :ref:`install_from_source`.

Compiling Matplotlib (or any other extension module, for that matter) requires
Visual Studio 2015 or later.
==========================
Installing for development
==========================
See :ref:`installing_for_devs`.

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.
76 changes: 76 additions & 0 deletions doc/users/installing_source.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
.. _install_from_source:

======================
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.

First you need to install the :ref:`dependencies`.

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.

.. _xcode: https://guide.macports.org/chunked/installing.html#installing.xcode

The easiest way to get the latest development version to start contributing
is to go to the git `repository <https://github.com/matplotlib/matplotlib>`_
and run::

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

or::

git clone git@github.com: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 <https://pypi.org/project/matplotlib/>`_.

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.

.. _setup.cfg: https://raw.githubusercontent.com/matplotlib/matplotlib/master/setup.cfg.template

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