Installation

pulse2percept requires Python 3.11 or newer.

Stable release

Install the latest stable release from PyPI with pip:

pip install pulse2percept

If you use uv, the equivalent command is:

uv pip install pulse2percept

For a uv-managed project, add pulse2percept as a dependency with:

uv add pulse2percept

The installer resolves NumPy and the other runtime dependencies automatically.

Latest development version

To install the current development version directly from GitHub:

pip install git+https://github.com/pulse2percept/pulse2percept

or with uv:

uv pip install git+https://github.com/pulse2percept/pulse2percept

This installs the latest code from the master branch. Unlike a PyPI wheel, a GitHub installation builds pulse2percept locally, so it requires Git and a working C compiler.

If you plan to modify pulse2percept itself, see the Developer Guide instead. It covers cloning the repository, editable installs, tests, and the contribution workflow.

Compatibility

Python	3.14	3.13	3.12	3.11	3.10	3.9	3.8	3.7
p2p 0.11 Residual Vision	Yes	Yes	Yes	Yes
p2p 0.10 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

Prebuilt wheels are available for 64-bit Linux, macOS 11 and later (Apple silicon and Intel), and 64-bit Windows. On other platforms, pip may build pulse2percept from source, which requires a C compiler. NumPy, Cython, and other build dependencies are installed automatically.

Our GitHub Action Runners test the current release on Linux, macOS, and Windows for every supported Python version listed above.

Upgrading and uninstalling

Upgrade to the latest stable release with:

pip install -U pulse2percept

or:

uv pip install -U pulse2percept

To uninstall:

pip uninstall pulse2percept

or:

uv pip uninstall pulse2percept

Troubleshooting

Unsupported Python version

pulse2percept requires Python 3.11 or newer. Check the interpreter you are using with:

python --version

If you have multiple Python installations, make sure you are installing into the environment you intend to use.

Installed, but Python cannot import pulse2percept

The most common cause is installing into a different Python environment from the one running your script or notebook.

Check which installation Python sees:

python -c "import pulse2percept as p2p; print(p2p.__version__); print(p2p.__file__)"

If that command fails, compare:

python -m pip show pulse2percept
python -m pip --version

Both commands should refer to the Python environment you intend to use.

GitHub installation fails

Installing directly from GitHub requires Git:

git --version

It also builds the Cython extensions locally, so a working C compiler is required.

On Windows, install Build Tools for Visual Studio and select Desktop development with C++.

On macOS, source builds may require OpenMP support. If the build fails while linking OpenMP, you can build without OpenMP acceleration:

P2P_DISABLE_OPENMP=1 pip install git+https://github.com/pulse2percept/pulse2percept

or:

P2P_DISABLE_OPENMP=1 uv pip install git+https://github.com/pulse2percept/pulse2percept

Failed building wheel during a normal PyPI install

A normal installation on a supported platform should use a prebuilt wheel. If pip install pulse2percept unexpectedly tries to compile the package, first make sure your Python version and platform are supported and update pip:

python -m pip install -U pip

Then try the installation again.

If the problem persists, please open an issue and include:

• your operating system;

• Python version;

• pulse2percept version;

• installer and version (for example, pip --version or uv --version);

• the complete installation error.