Installation

Build backends

mpi4py supports three different build backends: setuptools (default), scikit-build-core (CMake-based), and meson-python (Meson-based). The build backend can be selected by setting the MPI4PY_BUILD_BACKEND environment variable.

MPI4PY_BUILD_BACKEND

Choices:

"setuptools", "scikit-build-core", "meson-python"

Default:

"setuptools"

Request a build backend for building mpi4py from sources.

Using setuptools

Tip

Set the MPI4PY_BUILD_BACKEND environment variable to "setuptools" to use the setuptools build backend.

When using the default setuptools build backend, mpi4py relies on the legacy Python distutils framework to build C extension modules. The following environment variables affect the build configuration.

MPI4PY_BUILD_MPICC

The mpicc compiler wrapper command is searched for in the executable search path (PATH environment variable) and used to compile the mpi4py.MPI C extension module. Alternatively, use the MPI4PY_BUILD_MPICC environment variable to the full path or command corresponding to the MPI-aware C compiler.

MPI4PY_BUILD_MPILD

The mpicc compiler wrapper command is also used for linking the mpi4py.MPI C extension module. Alternatively, use the MPI4PY_BUILD_MPILD environment variable to specify the full path or command corresponding to the MPI-aware C linker.

MPI4PY_BUILD_MPICFG

If the MPI implementation does not provide a compiler wrapper, or it is not installed in a default system location, all relevant build information like include/library locations and library lists can be provided in an ini-style configuration file under a [mpi] section. mpi4py can then be asked to use the custom build information by setting the MPI4PY_BUILD_MPICFG environment variable to the full path of the configuration file. As an example, see the mpi.cfg file located in the top level mpi4py source directory.

MPI4PY_BUILD_CONFIGURE

Some vendor MPI implementations may not provide complete coverage of the MPI standard, or may provide partial features of newer MPI standard versions while advertising support for an older version. Setting the MPI4PY_BUILD_CONFIGURE environment variable to a non-empty string will trigger the run of exhaustive checks for the availability of all MPI constants, predefined handles, and routines.

The following environment variables are aliases for the ones described above. Having shorter names, they are convenient for occasional use in the command line. Its usage is not recommended in automation scenarios like packaging recipes, deployment scripts, and container image creation.

MPICC

Convenience alias for MPI4PY_BUILD_MPICC.

MPILD

Convenience alias for MPI4PY_BUILD_MPILD.

MPICFG

Convenience alias for MPI4PY_BUILD_MPICFG.

Using scikit-build-core

Tip

Set the MPI4PY_BUILD_BACKEND environment variable to "scikit-build-core" to use the scikit-build-core build backend.

When using the scikit-build-core build backend, mpi4py delegates all of MPI build configuration to CMake’s FindMPI module. Besides the obvious advantage of cross-platform support, this delegation to CMake may be convenient in build environments exposing vendor software stacks via intricate module systems. Note however that mpi4py will not be able to look for MPI routines available beyond the MPI standard version the MPI implementation advertises to support (via the MPI_VERSION and MPI_SUBVERSION macro constants in the mpi.h header file), any missing MPI constant or symbol will prevent a successful build.

Using meson-python

Tip

Set the MPI4PY_BUILD_BACKEND environment variable to "meson-python" to use the meson-python build backend.

When using the meson-python build backend, mpi4py delegates build tasks to the Meson build system.

Warning

mpi4py support for the meson-python build backend is experimental. For the time being, users must set the CC environment variable to the command or path corresponding to the mpicc C compiler wrapper.

Using pip

You can install the latest mpi4py release from its source distribution at PyPI using pip:

$ python -m pip install mpi4py

You can also install the in-development version with:

$ python -m pip install git+https://github.com/mpi4py/mpi4py

or:

$ python -m pip install https://github.com/mpi4py/mpi4py/tarball/master

Note

Installing mpi4py from its source distribution (available at PyPI) or Git source code repository (available at GitHub) requires a C compiler and a working MPI implementation with development headers and libraries.

Warning

pip keeps previously built wheel files on its cache for future reuse. If you want to reinstall the mpi4py package using a different or updated MPI implementation, you have to either first remove the cached wheel file with:

$ python -m pip cache remove mpi4py

or ask pip to disable the cache:

$ python -m pip install --no-cache-dir mpi4py

Using conda

The conda-forge community provides ready-to-use binary packages from an ever growing collection of software libraries built around the multi-platform conda package manager. Four MPI implementations are available on conda-forge: Open MPI (Linux and macOS), MPICH (Linux and macOS), Intel MPI (Linux and Windows) and Microsoft MPI (Windows). You can install mpi4py and your preferred MPI implementation using the conda package manager:

• to use MPICH do:

  $ conda install -c conda-forge mpi4py mpich
  

• to use Open MPI do:

  $ conda install -c conda-forge mpi4py openmpi
  

• to use Intel MPI do:

  $ conda install -c conda-forge mpi4py impi_rt
  

• to use Microsoft MPI do:

  $ conda install -c conda-forge mpi4py msmpi
  

MPICH and many of its derivatives are ABI-compatible. You can provide the package specification mpich=X.Y.*=external_* (where X and Y are the major and minor version numbers) to request the conda package manager to use system-provided MPICH (or derivative) libraries. Similarly, you can provide the package specification openmpi=X.Y.*=external_* to use system-provided Open MPI libraries.

The openmpi package on conda-forge has built-in CUDA support, but it is disabled by default. To enable it, follow the instruction outlined during conda install. Additionally, UCX support is also available once the ucx package is installed.

Warning

Binary conda-forge packages are built with a focus on compatibility. The MPICH and Open MPI packages are build in a constrained environment with relatively dated OS images. Therefore, they may lack support for high-performance features like cross-memory attach (XPMEM/CMA). In production scenarios, it is recommended to use external (either custom-built or system-provided) MPI installations. See the relevant conda-forge documentation about using external MPI libraries .

Linux

On Fedora Linux systems (as well as RHEL and their derivatives using the EPEL software repository), you can install binary packages with the system package manager:

• using dnf and the mpich package:

  $ sudo dnf install python3-mpi4py-mpich
  

• using dnf and the openmpi package:

  $ sudo dnf install python3-mpi4py-openmpi
  

Please remember to load the correct MPI module for your chosen MPI implementation:

• for the mpich package do:

  $ module load mpi/mpich-$(arch)
  $ python -c "from mpi4py import MPI"
  

• for the openmpi package do:

  $ module load mpi/openmpi-$(arch)
  $ python -c "from mpi4py import MPI"
  

On Ubuntu Linux and Debian Linux systems, binary packages are available for installation using the system package manager:

$ sudo apt install python3-mpi4py

Note that on Ubuntu/Debian systems, the mpi4py package uses Open MPI. To use MPICH, install the libmpich-dev and python3-dev packages (and any other required development tools). Afterwards, install mpi4py from sources using pip.

macOS

macOS users can install mpi4py using the Homebrew package manager:

$ brew install mpi4py

Note that the Homebrew mpi4py package uses Open MPI. Alternatively, install the mpich package and next install mpi4py from sources using pip.

Windows

Windows users can install mpi4py from binary wheels hosted on the Python Package Index (PyPI) using pip:

$ python -m pip install mpi4py

The Windows wheels available on PyPI are specially crafted to work with either the Intel MPI or the Microsoft MPI runtime, therefore requiring a separate installation of any one of these packages.

Intel MPI is under active development and supports recent version of the MPI standard. Intel MPI can be installed with pip (see the impi-rt package on PyPI), being therefore straightforward to get it up and running within a Python environment. Intel MPI can also be installed system-wide as part of the Intel HPC Toolkit for Windows or via standalone online/offline installers.