diff --git a/INSTALL.rst b/INSTALL.rst index fea85b3e8af6..1d8ea05e89f5 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -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`. + 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 `_. Install it using +``pip``: + +.. code-block:: sh python -m pip install -U pip python -m pip install -U matplotlib @@ -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 `_ 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 ---------------------------------- +========================= +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 `_ -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 `_ - cd matplotlib - python -m pip install -e . +- `ActiveState ActivePython + `_ -If you're not developing, it can be installed from the source directory with -a simple (just replace the last step):: +- `WinPython `_ - 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 ` 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. - -.. _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. diff --git a/doc/users/installing_source.rst b/doc/users/installing_source.rst new file mode 100644 index 000000000000..7d7d927cfd9a --- /dev/null +++ b/doc/users/installing_source.rst @@ -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 `_ +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 ` 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. + +.. _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.