Skip to content

Install guide tweaks #3397

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 4 commits into from
Aug 22, 2014
Merged

Install guide tweaks #3397

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5300ddb
DOC : slight re-organization of INSTALL
tacaswell Aug 22, 2014
1b59d20
DOC : reorganized/simplified INSTALL
tacaswell Aug 22, 2014
584f6af
DOC : tweaked text of INSTALL
tacaswell Aug 22, 2014
104f963
DOC : mention miniconda
tacaswell Aug 22, 2014
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
173 changes: 70 additions & 103 deletions INSTALL
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,100 +12,44 @@ installed, and how you want to use it. To avoid wading through all
the details (and potential complications) on this page, there are several
convenient options.

Installing pre-built packages
=============================

Most platforms : scientific Python distributions
================================================
------------------------------------------------

The first option is to use one of the pre-packaged python
distributions that already provide matplotlib built-in. The
Continuum.io Python distribution (`Anaconda
<https://store.continuum.io/cshop/anaconda/>`_ or `miniconda
<http://conda.pydata.org/miniconda.html>`_) and the Enthought
distribution `(Canopy) <https://www.enthought.com/products/canopy/>`_
are both excellent choices that "just work" out of the box for
Windows, OSX and common Linux platforms. Both of these distributions
include matplotlib and *lots* of other useful tools. Another
excellent alternative for Windows users is `Python (x, y)
<https://code.google.com/p/pythonxy>`_ .

The first option is to use one of the pre-packaged python distributions that
already provide matplotlib built-in. The Continuum.io Python distribution
`(Anaconda) <https://store.continuum.io/cshop/anaconda/>`_ and the Enthought
distribution `(Canopy) <https://www.enthought.com/products/canopy/>`_ are both
excellent choices that "just work" out of the box for Windows, OSX and common
Linux platforms. Both of these distributions include matplotlib and *lots* of
other useful tools. Another excellent alternative for Windows users is
`Python (x, y) <https://code.google.com/p/pythonxy>`_ .

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would consider mentioning miniconda since one of the most often raised complaints from users over Anaconda and Canopy is the large size and the many packages installed. Miniconda allows you to only install the packages you need.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A reduction in the size of the current installers. The Anaconda installers were becoming too big, due to the inclusion of some large packages. These packages have been removed from the installers, but are still supported and available in the repository, meaning you can still use conda to install them. These packages include mayavi, netcdf4, vtk, and 10 others.

It looks like they have done some thing about that already, but added miniconda link as well.

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 python-matplotlib``
* Fedora / Redhat : ``sudo yum install python-matplotlib``

Mac OSX - using pip
===================
Mac OSX : using pip
-------------------

If you are on Mac OSX you can probably install matplotlib binaries using the
standard Python installation program `pip <https://pypi.python.org/pip>`_.
See :ref:`installing-osx-binaries`.

Manually installing pre-built packages
======================================

General instructions
--------------------

For some people, the prepackaged pythons discussed above are not an
option. That's OK, it's usually pretty easy to get a custom install
working. You will first need to find out if you have python installed
on your machine, and if not, install it. The official python builds
are available for download `here <http://www.python.org/download>`_,
but OS X users please read :ref:`which-python-for-osx`.

Once you have Python up and running, you will need to install `numpy
<http://www.numpy.org/>`_. numpy provides high-performance array data
structures and mathematical functions, and is a requirement for
matplotlib. You can test your progress::

>>> import numpy
>>> print numpy.__version__

matplotlib requires numpy version |minimum_numpy_version| or later.
Although it is not a requirement to use matplotlib, we strongly
encourage you to install `ipython <http://ipython.org>`_, which is an
interactive shell for python that is matplotlib-aware.

Next, we need to get matplotlib installed. We provide prebuilt
binaries for OS X and Windows on the matplotlib `download
<http://matplotlib.org/downloads.html>`_. Click on
the latest release of the "matplotlib" package, choose your python
version (2.6, 2.7, 3.3, or 3.4) and your platform (macosx or win32). If you
have any problems, please check the :ref:`installing-faq`, search
using Google, and/or post a question the `mailing list
<http://sourceforge.net/project/showfiles.php?group_id=80706>`_.

If you are on Debian/Ubuntu linux, it suffices to do::
See :ref:`install_osx_binaries`.

> sudo apt-get install python-matplotlib

Instructions for installing our OSX binaries are found in the FAQ
:ref:`install_osx_binaries`.


Once you have ipython, numpy and matplotlib installed, you can use
ipython's "pylab" mode to have a MATLAB-like environment that automatically
handles most of the configuration details for you, so you can get up
and running quickly::

johnh@flag:~> ipython -pylab
Python 2.4.5 (#4, Apr 12 2008, 09:09:16)
IPython 0.9.0 -- An enhanced Interactive Python.

Welcome to pylab, a matplotlib-based Python environment.
For more information, type 'help(pylab)'.

In [1]: x = randn(10000)

In [2]: hist(x, 100)

Note that when testing matplotlib installations from the interactive
python console, there are some issues relating to user interface
toolkits and interactive settings that are discussed in
:ref:`mpl-shell`.

Installing on Windows
---------------------
Windows
-------

If you don't already have Python installed, we recommend using
one of the `scipy-stack compatible Python distributions
Expand Down Expand Up @@ -175,6 +119,8 @@ sys.prefix\Lib\site-packages\mpl_toolkits respectively, and install
Pillow, MiKTeX, GhostScript, ffmpeg, avconv, mencoder, ImageMagick, and
`Inkscape <http://inkscape.org/>`_.



.. _install_from_source:

Installing from source
Expand Down Expand Up @@ -213,31 +159,19 @@ e.g., if the header to some required library is in
.. _install_requirements:

Build requirements
==================
------------------

These are external packages which you will need to install before
installing matplotlib. If you are building on OSX, see
:ref:`build_osx`. If you are installing dependencies with a package
manager on Linux, you may need to install the development packages
(look for a "-dev" postfix) in addition to the libraries themselves.

.. note::

If you are on Debian/Ubuntu, you can get all the dependencies
required to build matplotlib with::

sudo apt-get build-dep python-matplotlib

If you are on Fedora/RedHat, you can get all the dependencies
required to build matplotlib by first installing ``yum-builddep``
and then running::

su -c "yum-builddep python-matplotlib"

This does not build matplotlib, but it does get the install the
build dependencies, which will make building from source easier.
Required Dependencies
^^^^^^^^^^^^^^^^^^^^^

:term:`python` 2.6, 2.7, 3.1 or 3.2
:term:`python` 2.6, 2.7, 3.3 or 3.4
`Download python <http://www.python.org/download/>`_.

:term:`numpy` |minimum_numpy_version| (or later)
Expand Down Expand Up @@ -267,7 +201,8 @@ libpng 1.2 (or later)
build support into the matplotlib single-click installer


**Optional GUI frameworks**
Optional GUI framework
^^^^^^^^^^^^^^^^^^^^^^

These are optional packages which you may want to install to use
matplotlib with a user interface toolkit. See
Expand All @@ -288,29 +223,29 @@ backends and the capabilities they provide.
The python wrappers for the wx widgets library for use with the
WX or WXAgg backend

**Optional external programs**

Optional external programs
^^^^^^^^^^^^^^^^^^^^^^^^^^
ffmpeg/avconv or mencoder
Required for the animation module to be save out put to movie
formats.

ImageMagick
Required for the animation module to be able to save to animated gif.

**Optional dependencies**
Optional dependencies
^^^^^^^^^^^^^^^^^^^^^

`Pillow http://python-imaging.github.io/`__
If Pillow is installed, matplotlib can read and write a larger
selection of image file formats.


:term:`freetype` 1.4 (or later)
library for reading true type font files. If you are a windows
user, you can ignore this since we build support into the
matplotlib single click installer.
library for reading true type font files.

**Required libraries that ship with matplotlib**

Required libraries that ship with matplotlib
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:term:`agg` 2.4
The antigrain C++ rendering engine. matplotlib links against the
agg template source statically, so it will not affect anything on
Expand All @@ -326,14 +261,46 @@ ImageMagick
`ttconv`
truetype font utility

.. _build_linux:

Building on Linux
-----------------

It is easiest to use your system package manager to install the dependencies.

If you are on Debian/Ubuntu, you can get all the dependencies
required to build matplotlib with::

sudo apt-get build-dep python-matplotlib

If you are on Fedora/RedHat, you can get all the dependencies required
to build matplotlib by first installing ``yum-builddep`` and then
running::

su -c "yum-builddep python-matplotlib"

This does not build matplotlib, but it does get the install the
build dependencies, which will make building from source easier.


.. _build_osx:

Building on OSX
===============
---------------

The build situation on OSX is complicated by the various places one
can get the libpng and freetype requirements (darwinports, fink,
/usr/X11R6) and the different architectures (e.g., x86, ppc, universal) and
the different OSX version (e.g., 10.4 and 10.5). We recommend that you build
the way we do for the OSX release: get the source from the tarball or the
git repository and follow the instruction in :file:`README.osx`.

.. _build_osx:

Building on Windows
-------------------

Building for source on windows can be difficult. Please see
`matplotlib-windbuild
<https://github.com/jbmohler/matplotlib-winbuild>`_ for detailed
instructions, dependency source blobs, and helper scripts.