Installation

To install the stable release of p2p, run:

pip install pulse2percept

pip installs NumPy and the other dependencies for you, and will only select a release that supports the Python version you are running (see Compatibility and Building from Source below).

We publish prebuilt wheels on PyPI for 64-bit Linux (manylinux, x86-64), macOS 11 and later (both Apple silicon and Intel), and 64-bit Windows. These wheels are not tied to a particular distribution or OS release beyond those minimums. You can find the full documentation here.

Compatibility and Building from Source

We do not publish wheels for 32-bit platforms or for musl-based distributions such as Alpine Linux. While other platforms are not explicitly supported, you may still be able to run p2p with minimal modifications: if pip does not find a prebuilt wheel for your system, it will attempt to install from source.

Note

You do not need to install NumPy or Cython yourself in order to build from source. They are declared as build requirements, so pip installs them into an isolated build environment automatically. What you do need is a C compiler: one is already present on most Linux and macOS systems, but on Windows you must install Visual Studio Build Tools and select “Desktop development with C++”.

The exception is pip install --no-build-isolation, which deliberately skips that step; there you must install NumPy and Cython yourself first.

Supported Python versions:

Python	3.14	3.13	3.12	3.11	3.10	3.9	3.8	3.7	3.6	3.5
p2p 0.10.0 Encoders	Yes	Yes	Yes	Yes
p2p 0.9.1		Yes	Yes	Yes	Yes
p2p 0.9 Cortex			Yes	Yes	Yes	Yes
p2p 0.8 Retina					Yes	Yes	Yes	Yes
p2p 0.7 Implants						Yes	Yes	Yes	Yes
p2p 0.6 API							Yes	Yes	Yes	Yes

Our GitHub Action Runners build and test p2p on the ubuntu-latest, windows-latest, and macos-latest images, on every Python version listed for the current release above. Those labels track whatever image GitHub currently ships, so the exact OS releases we test against change over time.

Note

Having trouble with the installation? Please refer to our Troubleshooting Guide.

Upgrading and Uninstalling

To upgrade p2p to the latest stable version:

pip install -U pulse2percept

To uninstall:

pip uninstall pulse2percept -y

Installing version 0.10.0.dev0 from source

If no prebuilt wheel is available for your system or you wish to contribue to p2p, you will want to install the latest version from source.

Prerequisites

Before getting started, you will need the following:

Python: You can check whether Python is already installed by typing python --version in a terminal or command prompt.

The latest development version supports the Python versions listed for the current release under Compatibility and Building from Source above.

If you don’t have Python, there are several options:
- If you’re unsure where to start, check out the Python Wiki.
- Python Anaconda (slow but comprehensive): comes with the conda package manager and a range of scientific software pre-installed (NumPy, SciPy, Matplotlib, etc.).
- Python Miniconda (fast but minimal): comes with the conda package manager but nothing else.
pip: On some platforms (e.g., macOS), you may have to install pip yourself. You can check if pip is installed on your system by typing pip --version in a terminal or command prompt.

If you don’t have pip, do the following:
- Download get-pip.py to your computer.
- Open a terminal or command prompt and navigate to the directory containing get-pip.py.
- Run the following command:
```
python get-pip.py
```
A C compiler: pulse2percept relies on C extension modules for code acceleration. On Unix platforms a compiler is already installed (gcc). On Windows you will have to install one yourself: get Build Tools for Visual Studio from the Microsoft website and make sure to select “Desktop Development with C++”, which includes the MSVC compiler libraries. You don’t need to install Visual Studio itself.

If you get an error saying unable to find vcvarsall.bat, then there is a problem with your Build Tools installation, in which case you should follow this guide.

Warning

Some guides on the web tell you to install MinGW instead of Visual Studio. However, this is not recommended for 64-bit platforms. When in doubt, follow the same guide.
Git: On Unix, you can install git from the command line. On Windows, make sure to download Git for Windows.
OpenMP (optional): OpenMP is used to parallelize code written in Cython or C. OpenMP is part of the GCC compiler on Unix, and part of the MinGW compiler on Windows. Follow these instructions to get it to work on macOS.

Note

You do not need to install NumPy or Cython by hand. Both are declared as build requirements in pyproject.toml, so pip installs them into an isolated build environment when it compiles p2p, and NumPy is installed again as a regular runtime dependency. Only if you build with pip install --no-build-isolation do you have to provide them yourself.

Obtaining the latest code from GitHub

Go to pulse2percept on GitHub and click on “Fork” in the top-right corner (you will need a GitHub account for this). This will allow you to work on your own copy of the code (https://github.com/<username>/pulse2percept) and contribute changes later on.
Clone the repository to get a local copy on your computer:
```
git clone https://github.com/<username>/pulse2percept.git
cd pulse2percept
```
Make sure to replace <username> above with your actual GitHub user name.

Note

A “fork” is basically a “remote copy” of a GitHub repository; i.e., creating “https://github.com/<username>/pulse2percept.git” from “https://github.com/pulse2percept/pulse2percept.git”.

A “clone” is basically a “local copy” of your GitHub repository; i.e., creating a local “pulse2percept” directory (including all the git machinery and history) from “https://github.com/<username>/pulse2percept.git”.

Building pulse2percept

Assuming you are still in the root directory of the git clone, type the following (note the .):

pip install -e .[dev]

Then from any Python console or script, try:

import pulse2percept as p2p

Important

Make sure you are reading the right version of the documentation: https://pulse2percept.readthedocs.io/en/latest (<– “latest”, not “stable”).

Keeping your fork up to date

Assuming you are working on your own fork, you may want to integrate new developments from the master branch from time to time.

If you have never upgraded your code before, add a new remote repository named “upstream” (you need to do this only once):

git remote add upstream https://github.com/pulse2percept/pulse2percept.git

Then type git branch to make sure you are on the right local branch. Finally, you can “sync” your fork by grabbing the latest code from the pulse2percept master branch:

git pull upstream master

Uninstalling pulse2percept

You can uninstall pulse2percept using pip:

pip uninstall -y pulse2percept

This works for both stable and latest releases.

In addition, if you installed from source, you may want to manually delete the directory where you cloned the git repository that contains all the source code.

Troubleshooting

Cannot install platform-specific wheel

Following recent trends in the NumPy and SciPy community, we do not provide wheels for 32-bit platforms, on any operating system or Python version we support.

The main reason is that p2p heavily depends on NumPy, SciPy, Matplotlib, and Scikit-Image. Since these packages no longer provide wheels for 32-bit platforms, we cannot either.

In this case, you will have to install p2p from source.

If you are getting this error message for a supposedly supported platform, please open an issue on GitHub.

Python ImportError: No module named pulse2percept

This is usually an issue related to $PATH, the environment variable that keeps track of all locations where pip should be looking for pulse2percept. Chances are that pip installed pulse2percept somewhere outside of $PATH.

You can check the installation location:

pip show pulse2percept

Then add the specificed location to $PATH; see PATH on Windows, PATH on macOS, PATH on Linux.

Error: numpy.ufunc size changed, may indicate binary incompatibility

This issue may arise with older p2p versions, or if one of the p2p dependencies was compiled using an older NumPy version.

Upgrading to the latest NumPy version should fix the issue:

pip install -U numpy

Then reinstall p2p according to the guide above.

Note

Still having trouble? Please open an issue on GitHub and describe your problem there. Make sure to mention your platform and whether you are installing using pip or from source.