Installation

axonforge is pure Python. There are no compiled extensions, no wheels to match against your platform and no build step — if NumPy imports, axonforge will install.

Requirements#

Dependency matrix for 0.7.2. Versions are lower bounds that are actually tested, not historical minimums.
Package	Version	Required?	Needed for
Python	3.10 – 3.13	yes	everything; 3.9 was dropped in 0.6.0
`numpy`	≥ 1.24	yes	arrays, memory mapping, feature maths
`scipy`	≥ 1.10	yes	filter design, `sosfiltfilt`, mixture fitting
`h5py`	≥ 3.8	optional	reading HDF5 datasets
`zstandard`	≥ 0.21	optional	reading and writing `.afz` containers
`matplotlib`	≥ 3.7	optional	`axonforge.plot` and `axonforge report`
`pytest`	≥ 7.4	dev only	the test suite

NumPy 2.x is supported from 0.7.0 onwards. SciPy below 1.10 will import but fail at the first bandpass call, because sosfiltfilt gained the argument we rely on in that release; the error message says so explicitly rather than failing silently.

Installing with pip#

python -m pip install axonforge

That gives you the core: readers for binary and NumPy inputs, filtering, detection, waveforms, sorting, quality metrics and statistics. The optional pieces are grouped into extras:

Extras and what each one adds.
Command	Adds	Enables
`pip install "axonforge[hdf5]"`	`h5py`	`af.io.read` on `.h5` files
`pip install "axonforge[afz]"`	`zstandard`	`.afz` read and write
`pip install "axonforge[plots]"`	`matplotlib`	`af.plot.*`, `axonforge report`
`pip install "axonforge[all]"`	all three	everything documented here

Nothing in the core imports the optional packages at module load time, so an environment without matplotlib still gives you a working detection pipeline. Calling a function that needs a missing extra raises an ImportError naming the extra to install.

From a source tarball#

tar xf axonforge-0.7.2.tar.gz
cd axonforge-0.7.2
python -m pip install .
python -m pytest -q          # 412 passed in ~90 s

The tarball contains the test suite and the synthetic benchmark used on the validation page, so a fresh install can be checked against the published numbers rather than taken on faith. The repository is self-hosted; write to maintainers@axonforge.dev for access if you intend to send patches.

Verifying the install#

python -c "import axonforge; print(axonforge.__version__)"
# 0.7.2

axonforge --version
# axonforge 0.7.2 (numpy 2.1.3, scipy 1.14.1, python 3.12.7)

axonforge selftest
# synthetic 4-channel recording, 10 s, SNR 6
# detected 1184 events, expected 1200 +/- 40  OK
# sorted into 3 units, expected 3                OK

axonforge selftest generates its own data in memory, so it touches no files and needs no extras. It is the fastest way to tell an environment problem from a data problem, and it is the first thing we ask about in a bug report.

Platform notes#

Linux and macOS: both used daily by the maintainers, 64-bit only.
Windows: the test suite passes, but memory mapping of files larger than 2 GB has only been exercised on 64-bit Python. If you work with hour-long 64-channel sessions there, read in chunks with af.io.read(..., chunk_s=60).
Memory: readers memory-map by default and filtering is done chunk-wise, so peak usage is roughly two chunks plus the spike table. A 32-channel, 10-minute session at 30 kHz is 1.15 GB on disk and peaked at 380 MB resident in our measurements.
No GPU path. There is none planned; the bottleneck for this channel count is disk reading, not arithmetic.