1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369
|
.. _installing-faq:
*************
Installation
*************
.. contents::
:backlinks: none
Report a compilation problem
============================
See :ref:`reporting-problems`.
matplotlib compiled fine, but nothing shows up when I use it
============================================================
The first thing to try is a :ref:`clean install <clean-install>` and see if
that helps. If not, the best way to test your install is by running a script,
rather than working interactively from a python shell or an integrated
development environment such as :program:`IDLE` which add additional
complexities. Open up a UNIX shell or a DOS command prompt and cd into a
directory containing a minimal example in a file. Something like
:file:`simple_plot.py` for example::
from pylab import *
plot([1,2,3])
show()
and run it with::
python simple_plot.py --verbose-helpful
This will give you additional information about which backends matplotlib is
loading, version information, and more. At this point you might want to make
sure you understand matplotlib's :ref:`configuration <customizing-matplotlib>`
process, governed by the :file:`matplotlibrc` configuration file which contains
instructions within and the concept of the matplotlib backend.
If you are still having trouble, see :ref:`reporting-problems`.
.. _clean-install:
How to completely remove matplotlib
===================================
Occasionally, problems with matplotlib can be solved with a clean
installation of the package.
The process for removing an installation of matplotlib depends on how
matplotlib was originally installed on your system. Follow the steps
below that goes with your original installation method to cleanly
remove matplotlib from your system.
Easy Install
------------
1. Delete the caches from your :ref:`.matplotlib configuration directory
<locating-matplotlib-config-dir>`.
2. Run::
easy_install -m matplotlib
3. Delete any .egg files or directories from your :ref:`installation
directory <locating-matplotlib-install>`.
Windows installer
-----------------
1. Delete the caches from your :ref:`.matplotlib configuration directory
<locating-matplotlib-config-dir>`.
2. Use :menuselection:`Start --> Control Panel` to start the :program:`Add and
Remove Software` utility.
Source install
--------------
Unfortunately::
python setup.py clean
does not properly clean the build directory, and does nothing to the
install directory. To cleanly rebuild:
1. Delete the caches from your :ref:`.matplotlib configuration directory
<locating-matplotlib-config-dir>`.
2. Delete the ``build`` directory in the source tree.
3. Delete any matplotlib directories or eggs from your :ref:`installation
directory <locating-matplotlib-install>`.
How to Install
==============
.. _install-from-git:
Source install from git
-----------------------
Clone the main source using one of::
git clone git@github.com:matplotlib/matplotlib.git
or::
git clone git://github.com/matplotlib/matplotlib.git
and build and install as usual with::
> cd matplotlib
> python setup.py install
.. 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 all of the
build dependencies, which will make building from source easier.
If you want to be able to follow the development branch as it changes
just replace the last step with (make sure you have **setuptools**
installed)::
> python setupegg.py develop
This creates links in the right places and installs the command
line script to the appropriate places.
.. note::
Mac OSX users please see the :ref:`build_osx` guide.
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 the `python
setupegg.py develop` command again to compile them.
There is more information on :ref:`using git <using-git>` in
the developer docs.
Linux Notes
===========
Because most Linux distributions use some sort of package manager,
we do not provide a pre-built binary for the Linux platform.
Instead, we recommend that you use the "Add Software" method for
your system to install matplotlib. This will guarantee that everything
that is needed for matplotlib will be installed as well.
If, for some reason, you can not use the package manager, Linux usually
comes with at least a basic build system. Follow the :ref:`instructions
<install-from-git>` found above for how to build and install matplotlib.
OS-X Notes
==========
.. _which-python-for-osx:
Which python for OS X?
----------------------
Apple ships with its own python, and many users have had trouble
with it. There are several alternative versions of python that
can be used. If it is feasible, we recommend that you use the enthought
python distribution `EPD <http://www.enthought.com/products/epd.php>`_
for OS X (which comes with matplotlib and much more). Also available is
`MacPython <http://wiki.python.org/moin/MacPython/Leopard>`_ or the
official OS X version from `python.org <http://www.python.org/download/>`_.
.. note::
Before installing any of the binary packages, be sure that all of the
packages were compiled for the same version of python.
Often, the download site for NumPy and matplotlib will display a
supposed 'current' version of the package, but you may need to choose
a different package from the full list that was built for your
combination of python and OSX.
.. _install_osx_binaries:
Installing OSX binaries
-----------------------
If you want to install matplotlib from one of the binary installers we
build, you have two choices: a mpkg installer, which is a typical
Installer.app, or a binary OSX egg, which you can install via
setuptools' easy_install.
The mkpg installer will have a "zip" extension, and will have a name
like :file:`matplotlib-0.99.0.rc1-py2.5-macosx10.5_mpkg.zip`.
The name of the installer depends on which versions of python, matplotlib,
and OSX it was built for. You need to unzip this file using either the
"unzip" command, or simply double clicking on the it. Then when you
double-click on the resulting mpkd, which will have a name like
:file:`matplotlib-0.99.0.rc1-py2.5-macosx10.5.mpkg`, it will run the
Installer.app, prompt you for a password if you need system-wide
installation privileges, and install to a directory like
:file:`/Library/Python/2.5/site-packages/` (exact path depends on your
python version). This directory may not be in your python 'path' variable,
so you should test your installation with::
> python -c 'import matplotlib; print matplotlib.__version__, matplotlib.__file__'
If you get an error like::
Traceback (most recent call last):
File "<string>", line 1, in <module>
ImportError: No module named matplotlib
then you will need to set your PYTHONPATH, eg::
export PYTHONPATH=/Library/Python/2.5/site-packages:$PYTHONPATH
See also ref:`environment-variables`.
.. _easy-install-osx-egg:
easy_install from egg
---------------------
You can also use the eggs we build for OSX (see the `installation
instructions
<http://pypi.python.org/pypi/setuptools#cygwin-mac-os-x-linux-other>`_
for easy_install if you do not have it on your system already). You
can try::
> easy_install matplotlib
which should grab the latest egg from the sourceforge site, but sometimes
the naming conventions for OSX eggs can be broken (see below).
Therefore, there is no guarantee the right egg will be found. We recommend
you download the latest egg from our `download site
<http://sourceforge.net/projects/matplotlib/files/>`_ directly to your
harddrive, and manually install it, eg::
> easy_install --install-dir=~/dev/lib/python2.5/site-packages/ matplotlib-0.99.0.rc1-py2.5-macosx-10.5-i386.egg
Naming convention issues
^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
This should no longer be an issue. If it is, please
report it to the mailing list.
Some users have reported problems with the egg for 0.98 from the
matplotlib download site, with ``easy_install``, getting an error::
> easy_install ./matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg
Processing matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg
removing '/Library/Python/2.5/site-packages/matplotlib-0.98.0-py2.5-
...snip...
Reading http://matplotlib.sourceforge.net
Reading http://cheeseshop.python.org/pypi/matplotlib/0.91.3
No local packages or download links found for matplotlib==0.98.0
error: Could not find suitable distribution for
Requirement.parse('matplotlib==0.98.0')
If you rename ``matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg`` to
``matplotlib-0.98.0-py2.5.egg``, ``easy_install`` will install it from
the disk. Many Mac OS X eggs have cruft at the end of the filename,
which prevents their installation through easy_install. Renaming is
all it takes to install them; still, it's annoying.
.. _install_from_source_on_osx_epd:
Building and installing from source on OSX with EPD
---------------------------------------------------
If you have the EPD installed (:ref:`which-python-for-osx`), it might turn out
to be rather tricky to install a new version of matplotlib from source on the
Mac OS 10.5 . Here's a procedure that seems to work, at least sometimes:
0. Remove the ~/.matplotlib folder ("rm -rf ~/.matplotlib").
1. Edit the file (make a backup before you start, just in case):
``/Library/Frameworks/Python.framework/Versions/Current/lib/python2.5/config/Makefile``,
removing all occurrences of the string ``-arch ppc``, changing the line
``MACOSX_DEPLOYMENT_TARGET=10.3`` to ``MACOSX_DEPLOYMENT_TARGET=10.5`` and
changing the occurrences of ``MacOSX10.4u.sdk`` into ``MacOSX10.5.sdk``
2. In
``/Library/Frameworks/Python.framework/Versions/Current/lib/pythonX.Y/site-packages/easy-install.pth``,
(where X.Y is the version of Python you are building against)
Comment out the line containing the name of the directory in which the
previous version of MPL was installed (Looks something like
``./matplotlib-0.98.5.2n2-py2.5-macosx-10.3-fat.egg``).
3. Save the following as a shell script, for example
``./install-matplotlib-epd-osx.sh``::
NAME=matplotlib
VERSION=v1.1.x
PREFIX=$HOME
#branch="release"
branch="master"
git clone git://github.com/matplotlib/matplotlib.git
cd matplotlib
if [ $branch = "release" ]
then
echo getting the maintenance branch
git checkout -b $VERSION origin/$VERSION
fi
export CFLAGS="-Os -arch i386"
export LDFLAGS="-Os -arch i386"
export PKG_CONFIG_PATH="/usr/x11/lib/pkgconfig"
export ARCHFLAGS="-arch i386"
python setup.py build
# use --prefix if you don't want it installed in the default location:
python setup.py install #--prefix=$PREFIX
cd ..
Run this script (for example ``sh ./install-matplotlib-epd-osx.sh``) in the
directory in which you want the source code to be placed, or simply type the
commands in the terminal command line. This script sets some local variable
(CFLAGS, LDFLAGS, PKG_CONFIG_PATH, ARCHFLAGS), removes previous installations,
checks out the source from github, builds and installs it. The backend should
to be set to MacOSX.
Windows Notes
=============
.. _windows-installers:
Binary installers for Windows
-----------------------------
If you have already installed python, you can use one of the
matplotlib binary installers for windows -- you can get these from the
`sourceforge download
<http://sourceforge.net/project/platformdownload.php?group_id=80706>`_
site. Choose the files that match your version of python (eg
``py2.5`` if you installed Python 2.5) which have the ``exe``
extension. If you haven't already installed python, you can get the
official version from the `python web site
<http://python.org/download/>`_.
There are also two packaged distributions of python that come
preloaded with matplotlib and many other tools like ipython, numpy,
scipy, vtk and user interface toolkits. These packages are quite
large because they come with so much, but you get everything with
a single click installer.
* The Enthought Python Distribution `EPD
<http://www.enthought.com/products/epd.php>`_
* `python (x, y) <http://www.pythonxy.com>`_
|