diff --git a/INSTALL b/INSTALL index 579bc580efea..622723836cbd 100644 --- a/INSTALL +++ b/INSTALL @@ -12,20 +12,27 @@ 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 +`_ or `miniconda +`_) and the Enthought +distribution `(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) +`_ . -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) `_ and the Enthought -distribution `(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) `_ . 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. @@ -33,79 +40,16 @@ 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 `_. -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 `_, -but OS X users please read :ref:`which-python-for-osx`. - -Once you have Python up and running, you will need to install `numpy -`_. 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 `_, 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 -`_. 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 -`_. - -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 @@ -175,6 +119,8 @@ sys.prefix\Lib\site-packages\mpl_toolkits respectively, and install Pillow, MiKTeX, GhostScript, ffmpeg, avconv, mencoder, ImageMagick, and `Inkscape `_. + + .. _install_from_source: Installing from source @@ -213,7 +159,7 @@ 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 @@ -221,23 +167,11 @@ installing matplotlib. If you are building on OSX, see 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 `_. :term:`numpy` |minimum_numpy_version| (or later) @@ -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 @@ -288,8 +223,8 @@ 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. @@ -297,7 +232,8 @@ ffmpeg/avconv or mencoder 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 @@ -305,12 +241,11 @@ ImageMagick :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 @@ -326,10 +261,32 @@ 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, @@ -337,3 +294,13 @@ can get the libpng and freetype requirements (darwinports, fink, 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 +`_ for detailed +instructions, dependency source blobs, and helper scripts.