Skip to content

Installation

pip / uv

Install the latest released btorch from PyPI:

pip install btorch

or

uv pip install btorch

Optional extras

The core install is lightweight. Heavy libraries are optional extras and are imported lazily; calling a feature whose library is missing raises an ImportError with the exact pip install "btorch[...]" command.

Extra Installs Enables
(core) torch, numpy, pandas, scipy, jaxtyping, matplotlib models, connectome tools, static plots
btorch[io] xarray, zarr, numcodecs, h5py, hdf5plugin btorch.io.serialization (xarray/Zarr save and load), btorch.utils.hdf5_utils
btorch[config] omegaconf, pyyaml btorch.utils.conf (OmegaConf helpers), btorch.utils.yaml_utils
btorch[fast] numba, polars optional accelerators (hex grid ops, use_polars aggregation); results are identical without them
btorch[gpu] triton GPU event timing in btorch.utils.bench.do_bench
btorch[analysis] powerlaw, nolds, fastdtw avalanche/DFA criticality, Lyapunov and entropy estimates, DTW trace clustering
btorch[viz] networkx, plotly interactive hex plots (btorch.visualisation.hex.interactive), graph plots
btorch[sparse] torch_scatter, torch_sparse optional, selectable sparse kernel backend (see below; needs PyG wheels)
btorch[examples] torchvision, seaborn, tqdm scripts in examples/
btorch[all] every extra above everything
pip install "btorch[io,analysis]"   # combine extras
pip install "btorch[all]"

CUDA support

btorch depends on PyTorch 2.3 or newer (torch.compiler.is_compiling). PyPI ships CPU-only torch by default. For CUDA, install PyTorch with the right compute platform first, then add btorch:

pip install torch --index-url https://download.pytorch.org/whl/cu1xx
pip install btorch

Or with uv:

uv pip install torch --torch-backend auto
uv pip install btorch

See the PyTorch Get Started page for other CUDA / ROCm variants.

conda / mamba

environment.yml bundles PyTorch with CUDA, pytorch_sparse, and all heavy dependencies via conda-forge and PyG channels:

conda env create -n btorch -f https://github.com/Criticality-Cognitive-Computation-Lab/btorch/raw/refs/heads/main/environment.yml
conda activate btorch

Or with mamba:

mamba env create -n btorch -f https://github.com/Criticality-Cognitive-Computation-Lab/btorch/raw/refs/heads/main/environment.yml
mamba activate btorch

Install from source control

Btorch is fast evolving. For the latest unreleased changes, install directly from the repository:

pip install git+https://github.com/Criticality-Cognitive-Computation-Lab/btorch.git

Gitee mirror alternative:

pip install git+https://gitee.com/alexfanqi/btorch.git

Editable install (development)

Clone the repo and install in editable mode:

git clone https://github.com/Criticality-Cognitive-Computation-Lab/btorch.git
cd btorch
pip install -e . --config-settings editable_mode=strict

If you use uv, clone and sync the lockfile:

git clone https://github.com/Criticality-Cognitive-Computation-Lab/btorch.git
cd btorch
uv sync --group dev --all-extras
source .venv/bin/activate
pip install -e . --config-settings editable_mode=strict

For CUDA with uv, install torch with the right backend first:

uv venv .venv-cuda
uv pip install torch --torch-backend auto --python .venv-cuda/bin/python
uv pip install -e . --python .venv-cuda/bin/python

Optional: torch_sparse backend

Sparse connections (btorch.models.connection.SparseConnection) need only PyTorch. They train, run on CPU and GPU, and compile with torch.compile(..., fullgraph=True) without torch_sparse.

If torch_sparse is installed, btorch registers it as an additional kernel backend. It is never selected automatically; choose it explicitly with btorch.sparse.runtime.use_backend("torch_sparse") (see the sparse connectivity guide). Use prebuilt wheels from the PyG repository matching your PyTorch and CUDA version:

# Example for PyTorch 2.7 with CUDA 12.6
pip install torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-2.7.0+cu126.html

If torch_sparse is absent, nothing changes: the default backend is used.

Verify

python -c "import btorch; import torch; print(btorch.__version__, torch.__version__, torch.cuda.is_available())"