NeuronScope
Get StartedStablesince v0.9.2

Installation

Install NeuronScope with the tool you already use — pip, uv, conda, source, or Docker — with honest notes on what each option costs.

Audience: New usersRead: 6 minEdit on GitHub

NeuronScope is a pure-Python library with optional native accelerators. It installs cleanly on Linux, macOS, and Windows against CPython 3.10+. Every install method below produces the same on-disk layout and the same runtime behaviour; pick the one that matches your project tooling.

Supported environments

  • Python: 3.10, 3.11, 3.12, 3.13. Older interpreters are not supported.
  • Operating systems: Linux (glibc 2.28+), macOS 12+, Windows 10+.
  • Accelerators: CUDA 12.1+, ROCm 6.0+, Apple Metal, or CPU-only. NeuronScope does not ship its own CUDA wheels — it uses whatever your framework already installed.

pip

The default install. Uses only the standard resolver and works inside a plainvenv.

shellbash
$ python -m venv .venv && source .venv/bin/activate
$ pip install --upgrade pip
$ pip install neuronscope==0.9.2
$ python -c 'import neuronscope; print(neuronscope.__version__)'
0.9.2

uv

uv is the fastest resolver in practice today. NeuronScope publishes auv.lock-friendly wheel and has no dependencies that require custom index configuration.

shellbash
$ uv init myproject && cd myproject
$ uv add neuronscope==0.9.2
$ uv run python -c 'import neuronscope as ns; ns.doctor()'

conda

Conda users can install from conda-forge. This is the recommended path when your framework (PyTorch, JAX) is also managed by conda so that BLAS and CUDA are consistent across the environment.

shellbash
$ conda create -n ns python=3.12 -y && conda activate ns
$ conda install -c conda-forge neuronscope=0.9.2

From source

Install from source only when contributing or when you need an unreleased fix. The source tree uses hatch for builds and pytest for the test matrix.

shellbash
$ git clone https://github.com/neuronscope/neuronscope.git
$ cd neuronscope
$ uv sync --all-extras
$ uv run pytest -q

Docker

The official image is minimal — a slim Python base, NeuronScope, and nothing else. Add your framework of choice as a second layer. GPU passthrough uses the standard--gpus flag.

Dockerfile·
·shell
FROM ghcr.io/neuronscope/neuronscope:0.9.2
RUN pip install torch==2.4.1
COPY . /workspace
WORKDIR /workspace
CMD ["python", "-m", "your_experiment"]

Optional extras

Extras keep the base install small. Install only the ones you need.

  • [torch] — PyTorch adapter and tensor helpers.
  • [jax] — JAX adapter with jit-friendly recorders.
  • [hf] — Hugging Face dataset and model integrations.
  • [viz] — Diagram export dependencies (headless Chromium).
  • [all] — Everything above, for people who prefer one big install.
shellbash
$ pip install "neuronscope[torch,hf]==0.9.2"

Verify the install

The ns doctor command reports the resolved environment, the installed extras, the detected accelerator, and any missing pieces. Run it after every install.

shellbash
$ ns doctor
$ 
python       3.12.4 (cpython)
neuronscope  0.9.2
torch        2.4.1 (cuda 12.1)
adapter      torch  ok
adapter      jax    not installed (extras missing)
device       NVIDIA A100 80GB

Next steps

  1. Read the quickstart to record your first activation.
  2. Skim the system architecture to understand what the library is doing on your behalf.
  3. Bookmark the fingerprinting chapter — it is the primitive everything else composes on top of.
Related