July 4, 2026 · 12 min read

pip install neurocuda Guide

This pip install neurocuda guide covers environment setup, PyTorch and CUDA pairing, optional backends, your first conversion, and fixes for the errors that block most installs.

Most people who search pip install neurocuda already have a PyTorch model and hit friction at environment setup: wrong CUDA wheel, missing torchvision, or a corporate proxy blocking PyPI. This guide walks from empty venv to a validated SNN on GPU or CPU.

NeuroCUDA is on PyPI and GitHub, maintained by QuantaraCore. Product docs: /neurocuda. Technical benchmarks: paper.pdf.

System requirements

Step 1: Create a virtual environment

# Linux / macOS
python3 -m venv neurocuda-env
source neurocuda-env/bin/activate

# Windows PowerShell
python -m venv neurocuda-env
.\neurocuda-env\Scripts\Activate.ps1

Isolating dependencies prevents pip install neurocuda from conflicting with system packages or other ML projects.

Step 2: Install PyTorch first

Install PyTorch before NeuroCUDA. Visit pytorch.org/get-started and select your CUDA version.

# Example: CUDA 12.1 wheel
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# CPU only
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

Verify GPU visibility:

python -c "import torch; print(torch.__version__); print('CUDA:', torch.cuda.is_available())"

Step 3: pip install neurocuda

pip install neurocuda

For GPU backend, Loihi 2 simulator, and NIR export extras:

pip install neurocuda[all]

Confirm import:

python -c "import neurocuda; print(neurocuda.__version__)"

Package page: pypi.org/project/neurocuda. Source: GitHub.

Step 4: First conversion smoke test

import torch
import torch.nn as nn
from torch.utils.data import DataLoader, TensorDataset
import neurocuda

# Tiny ANN + fake calibration data
model = nn.Sequential(nn.Linear(784, 128), nn.ReLU(), nn.Linear(128, 10))
model.eval()
x = torch.randn(200, 784)
y = torch.randint(0, 10, (200,))
loader = DataLoader(TensorDataset(x, y), batch_size=32)

snn = neurocuda.convert(model, loader, timesteps=8)
neurocuda.compile(snn, target="cpu")
print("pip install neurocuda: OK")

If this prints without exception, your pip install neurocuda setup is sound. Scale to real datasets with convert PyTorch to SNN.

CUDA and PyTorch version matrix

Optional backends after install

neurocuda.compile(snn, target="gpu")        # NVIDIA CUDA
neurocuda.compile(snn, target="cpu")        # reference CPU
neurocuda.compile(snn, target="loihi2_sim")   # Loihi 2 IF equations
neurocuda.to_nir(snn, "model.nir")          # NIR export

GPU and CPU backends are cross-validated in the technical report. Loihi 2 sim does not require Intel Lava or INRC membership - see Loihi 2 PyTorch without Lava.

Troubleshooting pip install neurocuda

ImportError: No module named 'torch'

PyTorch is a prerequisite, not bundled. Run pip install torch torchvision first.

SSL certificate errors on corporate networks

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org neurocuda

Use only if your IT policy allows; prefer proper certificate configuration when possible.

Version conflict with existing packages

Fresh venv resolves 90% of conflicts. Avoid mixing conda and pip in the same environment for NeuroCUDA projects.

Conversion runs but accuracy is ~10%

Install succeeded; conversion hyperparameters need tuning. See accuracy drop guide and QCFS threshold guide - not a pip issue.

Production pinning

# requirements.txt example
torch==2.2.0
torchvision==0.17.0
neurocuda>=0.1.0

Pin the same PyTorch version you used to train the ANN. Mismatched torch versions between training and conversion can shift BatchNorm statistics subtly.

Docker and CI installs

Container images should install PyTorch from the official wheel index first, then run pip install neurocuda in the same layer to keep image size predictable. For GitHub Actions, cache the pip directory keyed on requirements.txt hashes. A minimal CI smoke test after install catches broken torch pairings before merge:

# .github/workflows/neurocuda-smoke.yml (sketch)
- run: pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
- run: pip install neurocuda
- run: python -c "import neurocuda; import torch; print('OK')"

GPU runners need the matching CUDA wheel in the workflow matrix, not the CPU index URL. Document the chosen torch build in your README so teammates reproduce the same pip install neurocuda environment on laptops and servers.

Install paths compared

What pip install neurocuda does not include

• Intel Lava SDK (archived anyway - alternatives)
• Physical Loihi 2 hardware access (INRC program separate)
• Pretrained CIFAR-10 weights (train or download your own checkpoint)
• CUDA toolkit system install (PyTorch wheels bundle runtime libraries)

Frequently asked questions

Install: pip install neurocuda · Product page · PDF report