Installation#

This page describes how to install SuperNeuroMAT.

Setting up your environment#

Note

If you’re on Ubuntu or a Debian-based Linux distribution, you may need to use pyenv to install Python 3.11 or later. See the pyenv installation instructions. You need to do this before creating the virtual environment.

Important

Windows users: please DO NOT use Python from the Microsoft Store. Instead, download and install the latest version of Python from the Python website. Make sure to check the box to add Python to your PATH:

Add Python to PATH

If you didn’t do this when installing Python, you’ll need to add it manually. See Excursus: Setting environment variables or How to Add Python to PATH. Or, uninstall and reinstall Python (You may need to re-pip install system Python packages).

To install SuperNeuroMAT, we recommend using uv.

Install UV for faster installs
Install uv <pyuv/uv> for faster installs#
pip install uv -U

The -U flag is shorthand for --upgrade.

You can preface most pip install commands with uv for much faster installation. uv pip install may not work for some packages. If you get an error, try using regular pip install first.

The recommended way to install SuperNeuroMAT is with a virtual environment.

Virtual environments are isolated Python environments that allow you to install packages without affecting your system Python installation.

First, you need to choose a location to store your virtual environment.

mkdir foovenv
cd foovenv
Create a virtual environment#
uv venv
Create a virtual environment#
pip install virtualenv
virtualenv .venv --prompt .

This will create a virtual environment .venv folder in your current directory.

Now, we need to activate the virtual environment.

Activating the virtual environment#

Once you have created your virtual environment, you need to activate it.

Make sure you’re in the directory where you created the virtual environment. In this example we’re in the foovenv/ folder.

.venv\Scripts\activate

source .venv/bin/activate

Note

The above activation command is for the default shell environments, such as bash, zsh, or sh on Unix, or cmd and powershell on Windows. If you’re using a different shell, such as fish or Nushell, you may need to use a different activation file.

source .venv/bin/activate.fish

overlay use .venv\Scripts\activate.nu

overlay use .venv/bin/activate.nu

You should see the name of your virtual environment in parentheses at the beginning of your terminal prompt:

(foovenv) C:\foovenv>

(foovenv) user@host:~/foovenv$

To deactivate the virtual environment, use the deactivate command:

deactivate

Installing SuperNeuroMAT#

uv pip install superneuromat

Note

It’s possible to install SuperNeuroMAT to the global system Python installation with the --system flag. However, this is not recommended, as it may cause conflicts with other packages.

pip install superneuromat

While you’re here, let’s also install pyreadline3 which makes the python shell much more user-friendly.

uv pip install pyreadline3

pip install pyreadline3

If the installation was successful, you should be able to open a python shell and import the package:

python#
Python 3.10.0 (or newer)
Type "help", "copyright", "credits" or "license" for more information.
>>> import superneuromat
>>>

If you installed pyreadline3, you can exit the python shell with Ctrl+C to stop currently running commands and then Ctrl+D or quit() to quit the python REPL.

Installing with Numba support#

If you want to use SuperNeuroMAT with the 'jit' backend or with the CUDA 'gpu' backend, you’ll need to install Numba.

Don’t forget to activate the virtual environment!

Activating the virtual environment

For just the 'jit' backend:

uv pip install superneuromat[jit]

For both the 'jit' and 'gpu' backends:

uv pip install superneuromat[cuda]

For just the 'jit' backend:

pip install superneuromat[jit]

For both the 'jit' and 'gpu' backends:

pip install superneuromat[cuda]

To use CUDA with Numba installed this way, you’ll also need to install the CUDA SDK from NVIDIA. See Installing using pip on x86/x86_64 Platforms.

Once you have numba.cuda.is_available(), SuperNeuroMAT will be able to use the CUDA 'gpu' backend.

python -c "import numba.cuda; assert numba.cuda.is_available()"

See also

Don’t know if you need these? See Considerations for Speed to learn more about SuperNeuroMAT’s different backends.

Development Installations#

If you intend to contribute to SuperNeuroMAT, you should follow the installation guide for development instead.

Installing for Development

WSL Installation#

Although SuperNeuroMAT works natively on Windows, you can also install SuperNeuroMAT in a Windows Subsystem for Linux (WSL) environment.

First, you need to install WSL.

Then, follow the Installing SuperNeuroMAT or Installing for Development instructions as if you were on Linux.

Finished installing? Check out the Basic Usage tutorial.

First Run Tutorial