### Navigation

- next
- previous |
- MPI for Python v1.3 documentation »

# Installation

## Requirements

You need to have the following software properly installed in order to build MPI for Python:

- A working MPI distribution, preferably a MPI-2 one built with shared/dynamic libraries.

  Note

  If you want to build some MPI implementation from sources, check the instructions at Building MPI from sources in the appendix.

- A Python 2.3 to 2.7 or 3.0 to 3.1 distribution, with Python library preferably built with shared/dynamic libraries.

  Note

  Mac OS X users employing a Python distribution built with universal binaries may need to temporarily set the environment variables `MACOSX_DEPLOYMENT_TARGET`, `SDKROOT`, and `ARCHFLAGS` to appropriate values in the shell before trying to build/install MPI for Python. Check the instructions at Mac OS X and Universal/SDK Python builds in the appendix.

  Note

  Some MPI-1 implementations do require the actual command line arguments to be passed in `MPI_Init()`. In this case, you will need to use a rebuilt, MPI-enabled, Python interpreter executable. MPI for Python has some support for alleviating you from this task. Check the instructions at MPI-enabled Python interpreter in the appendix.

## Using pip or easy_install

If you already have a working MPI (either if you installed it from sources or by using a pre-built package from your favourite GNU/Linux distribution) and the mpicc compiler wrapper is on your search path, you can use pip:

    $ [sudo] pip install mpi4py

or alternatively setuptools easy_install (deprecated):

    $ [sudo] easy_install mpi4py

Note

If the mpicc compiler wrapper is not on your search path (or if it has a different name) you can use env to pass the environment variable `MPICC` providing the full path to the MPI compiler wrapper executable:

    $ [sudo] env MPICC=/path/to/mpicc pip install mpi4py

    $ [sudo] env MPICC=/path/to/mpicc easy_install mpi4py

## Using distutils

MPI for Python uses a standard distutils-based buildsystem. However, some distutils commands (like build) have additional options:

- --mpicc= : let you specify a special location or name for the mpicc compiler wrapper.
- --mpi= : let you pass a section with MPI configuration within a special configuration file.
- --configure : runs exhaustive tests for checking about missing MPI types/constants/calls. This option should be passed in order to build MPI for Python against old MPI-1 implementations, possibly providing a subset of MPI-2.

### Downloading

The MPI for Python package is available for download at the project website generously hosted by Google Code. You can use curl or wget to get a release tarball:

    $ curl -O http://mpi4py.googlecode.com/files/mpi4py-X.X.X.tar.gz

    $ wget http://mpi4py.googlecode.com/files/mpi4py-X.X.X.tar.gz

### Building

After unpacking the release tarball:

    $ tar -zxf mpi4py-X.X.X.tar.gz
    $ cd mpi4py-X.X.X

the distribution is ready for building.

- If you use a MPI implementation providing a mpicc compiler wrapper (e.g., MPICH 1/2, Open MPI, LAM), it will be used for compilation and linking. This is the preferred and easiest way of building MPI for Python.

  If mpicc is located somewhere in your search path, simply run the build command:

      $ python setup.py build

  If mpicc is not in your search path or the compiler wrapper has a different name, you can run the build command specifying its location:

      $ python setup.py build --mpicc=/where/you/have/mpicc

- Alternatively, you can provide all the relevant information about your MPI distribution by editing the file called `mpi.cfg`. You can use the default section `[mpi]` or add a new, custom section, for example `[my_mpi]` (see the examples provided in the `mpi.cfg` file):

      [mpi]

      include_dirs         = /usr/local/mpi/include
      libraries            = mpi
      library_dirs         = /usr/local/mpi/lib
      runtime_library_dirs = /usr/local/mpi/lib

      [other_mpi]

      include_dirs         = /opt/mpi/include ...
      libraries            = mpi ...
      library_dirs         = /opt/mpi/lib ...
      runtime_library_dirs = /op/mpi/lib ...

      ...

  and then run the build command, perhaps specifying you custom configuration section:

      $ python setup.py build --mpi=other_mpi

### Installing

After building, the distribution is ready for install.

If you have root privileges (either by log-in as the root user of by using sudo) and you want to install MPI for Python in your system for all users, just do:

    $ python setup.py install

The previous steps will install the `mpi4py` package at standard location `prefix/lib/pythonX.X/site-packages`.

If you do not have root privileges or you want to install MPI for Python for your private use, you have two options depending on the target Python version.

- For Python 2.6 and up:

      $ python setup.py install --user

- For Python 2.5 and below (assuming your home directory is available through the `HOME` environment variable):

      $ python setup.py install --home=$HOME

  Finally, add `$HOME/lib/python` or `$HOME/lib64/python` to your `PYTHONPATH` environment variable.

### Testing

Issuing at the command line:

    $ mpiexec -n 5 python demo/helloworld.py

or (in the case of older MPI-1 implementations):

    $ mpirun -np 5 python demo/helloworld.py

will launch a five-process run of the Python interpreter and run the test scripts `demo/helloworld.py`.

You can also run all the unittest scripts:

    $ mpiexec -n 5 python test/runalltest.py

or, if you have nose unit testing framework installed:

    $ mpiexec -n 5 nosetests -w test

### Navigation

- next
- previous |
- MPI for Python v1.3 documentation »