Because pulse2percept is in active development, there are at least three versions to choose from:
stable: Our stable release can be installed with:
pip install pulse2percept
It may not have all the latest features, but the ones it has are well tested. You can read the corresponding docs here.
If you have previously installed p2p this way and wish to upgrade it to the latest stable version, use the
-Uoption with pip:
pip install -U pulse2percept
latest: Our bleeding-edge version can be installed with:
pip install git+https://github.com/pulse2percept/pulse2percept
Developer version: Finally, if you wish to contribute to the p2p code base, you will need to install p2p from source.
Having trouble with the installation? Please refer to our Troubleshooting Guide.
Installing version 0.8.0 from source¶
If you want to contribute to the p2p code base, you will need to install p2p from source.
Similarly, if your platform is not officially supported (and hence we do not have a wheel for it), you will need to build p2p from source. Following recent trends in the NumPy and SciPy community, we do not provide wheels for 32-bit platforms (this includes all Unix platforms and Windows starting with Python 3.10).
Before getting started, you will need the following:
Python: You can check whether Python is already installed by typing
python --versionin a terminal or command prompt.
pulse2percept supports these Python versions:
Python 3.10 3.9 3.8 3.7 3.6 3.5 3.4 2.7 p2p 0.8 Yes Yes Yes Yes p2p 0.7 Yes Yes Yes Yes p2p 0.6 Yes Yes Yes Yes p2p 0.5 Yes Yes Yes p2p 0.4 Yes Yes Yes
If you don’t have Python, there are several options:
- If you’re unsure where to start, check out the Python Wiki.
- Python Anaconda (good but slow in 2020): 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 --versionin 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
Run the following command:
NumPy: Once you have Python and pip, simply open a terminal and type
pip install numpy.
Cython (>= 0.28): pulse2percept relies on C extension modules for code acceleration. These require a C compiler, which on Unix platforms is already installed (
gcc). However, on Windows you will have to install a compiler yourself:
Install Build Tools for Visual Studio 2019 from the Microsoft website. Note that the build tools for Visual Studio 2015 or 2017 should work as well (Python >= 3.7 requires C++ 14.X to be exact). Also note that you don’t need to install Visual Studio itself.
pip install Cython
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.
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 this guide.
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.
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.
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”.
Install all dependencies listed in
requirements.txtby using the following command:
pip install -r requirements.txt
This includes Cython. If you are on Windows, make sure you followed the steps outlined above to install a suitable C compiler (see Prerequisites above).
If you plan on contributing to pulse2percept, you should also install all developer dependencies listed in
pip install -r requirements-dev.txt
Assuming you are still in the root directory of the git clone, type the
following (note the
pip install -e .
Then from any Python console or script, try:
import pulse2percept as p2p
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
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
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.
Cannot install platform-specific wheel¶
Following recent trends in the NumPy and SciPy community, we do not provide wheels for 32-bit platforms (this includes all Unix platforms and Windows starting with Python 3.10).
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
You can check the installation location:
pip show pulse2percept
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.
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.