Brian2: a clock-driven simulator where you write the model and it writes the code

A simulator written for the scientist, not for the cluster

Brian is a free, open source simulator for spiking neural networks, written in the Python programming language and available on almost all platforms. The project states its design goal directly: a simulator should not only save the time of processors, but also the time of scientists, and Brian is therefore designed to be easy to learn and use, highly flexible and easily extensible.

That second clause is the interesting one, because it tells you what kind of project this is. A simulator that saves processor time is a performance story. One that saves scientist time is a usability story, and that shows in the design: you write a differential equation in a notation that looks like the equation in the paper, you write a threshold condition, you write a synaptic rule, and the simulator works out the integration method and generates the code.

The description in the README is a clock-driven simulator for spiking neural networks, and the project name is the version 2 of the simulator. The homepage is briansimulator.org and the documentation is at brian2.readthedocs.io, and the project has been at this long enough to have a peer-reviewed article, which the README asks you to cite if you use Brian for published research: Stimberg, Brette and Goodman, Brian 2, an Intuitive and Efficient Neural Simulator, eLife 8 in 2019, article e47314.

The primary language is Python, the default branch is master, and the repository is not archived with the last push on 2026-10-15, so the project is being actively worked on despite the absence of GitHub releases, which is normal for a project distributed through PyPI and conda-forge.

The audience is computational neuroscience. The topic tags say it plainly: computational-neuroscience, neuroscience, biological-simulations, differential-equations, spiking-neural-networks and simulation-framework. There is also code-generation among the tags, which is the mechanism rather than the subject, and we will come back to it.

The code generation path, and why setup.py builds Cython extensions

The repository layout tells you the mechanism, and the setup.py in it is unusually explicit.

# Now Cython is required and no python fallback is possible
spike_queue_ext = require_cython_extension(
    module_path=["brian2", "synapses"],
    module_name="cythonspikequeue",
)

and again for the memory module:

dynamic_array_ext = require_cython_extension(
    module_path=["brian2", "memory"],
    module_name="cythondynamicarray",
    extra_include_dirs=["brian2/devices/cpp_standalone/brianlib"]
)

Two Cython extensions are built at install time, one in the synapses package for the spike queue and one in the memory package for the dynamic array, and the second one reaches into the C++ standalone device code under brian2/devices/cpp_standalone/brianlib. The comment about Cython being required and no Python fallback being possible is the key statement: the performance path is not optional.

The helper function itself is straightforward setuptools work. It locates a.pyx file under the given module path, builds a full module name from the path, adds numpy.get_include() to the include directories, and returns an Extension object.

So there are two execution targets in one package, and the choice between them is where a user of Brian actually makes decisions. There is the Cython target, which is what the two extensions above serve, and which is the standard option for speed. And there is the C++ standalone target, whose brianlib directory the second extension compiles against, which produces a standalone executable with no Python dependency at all for running large simulations.

The examples/ directory in the repository is organised mostly by model type: IF_curve_Hodgkin_Huxley.py, IF_curve_LIF.py, adaptive_threshold.py, coupled_oscillators.py, phase_locking.py, reliability.py and non_reliability.py at the top level, and then directories for advanced, compartmental, frompapers, multiprocessing, standalone and synapses. The frompapers/ directory is worth a look for anyone evaluating the project, because the examples that reproduce published figures are the best available evidence that the simulator gets the biology right.

The dependency stack, and a floor that has been moving

The README's dependency list is explicit, and it is where the version floor for your own environment comes from.

The required packages are Python >= 3.12, NumPy >= 2.0, SymPy >= 1.2, Cython >= 0.29.21, PyParsing >= 3, Jinja2 >= 2.7, setuptools >= 61, py-cpuinfo, which is only required on Windows, and packaging. For full functionality the README also suggests GSL >=1.16, SciPy >=0.13.3 and Matplotlib >= 2.0. Documentation needs Sphinx >=7,<9, ipython >=5 and sphinx-tabs, and the test suite needs pytest >= 8 with pytest-xdist optional.

There is a mismatch between the README and the package metadata worth flagging before you install. The README says Python >= 3.12 and NumPy >= 2.0, while pyproject.toml says requires-python of >=3.13 and pins numpy>=2.3.0. The pyproject values are the ones pip enforces, so 3.12 and an older NumPy will not install cleanly even though the README implies they might.

The pyproject also lists pyparsing>=3,!=3.2.4, so one specific patch release is excluded, and it classifies the project as Development Status :: 5 - Production/Stable with the Intended Audience of Science/Research.

The optional dependency groups are minimal and modern. The test group is pytest>=8, pytest-xdist>=1.22.3, pytest-cov>=2.0 and pytest-timeout, and the docs group is sphinx>=7,<9, ipython>=8.32.0 and sphinx-tabs.

The distribution reach is wide, and the badges in the README enumerate it: PyPI, conda-forge, a Debian package, a Fedora package, Spack, the AUR, a Docker image published as briansimulator/brian, a Zenodo DOI, and two Software Heritage archives, one for the repository and one for a release.

The software-package and container angles matter for a different reason. A neuroscience group running a cluster of long simulations is exactly the case where a Docker image and a pinned conda environment save each member from solving the build themselves, and the Zenodo and Software Heritage identifiers mean a specific published result can be traced back to a specific piece of source.

Running it: the binder quickstart and the C++ standalone path

The quick start offered in the README is a hosted notebook rather than a local installation, and that choice says something about the intended first experience.

Try out Brian on the mybinder service, with a badge linking to a brian2-binder notebook on mybinder.org. No installation, no dependency resolution, and a working example in the browser. For a project with a large scientific dependency stack, that is a deliberate way to lower the barrier to the first successful simulation.

The local path is the pip or conda install, and for running a large simulation the interesting target is the standalone one. The examples/standalone/ directory in the repository holds the scripts for that mode, and the C++ code lives under brian2/devices/cpp_standalone/. The point of the standalone device is that the compiled simulation does not need Python running, which matters when the simulation is scheduled on a cluster node as a batch job.

The repository also carries the tooling a simulator project needs around its code. There is a dev/ directory, a docker/ directory, a docs_sphinx/ directory for the documentation, a tutorials/ directory, and an examples/ directory. There are .devcontainer/ and .vscode/ directories for development environments, a .coveragerc and a .pre-commit-config.yaml for the test and lint pipeline, and a .codemeta/ directory with a codemeta.json for metadata submission.

The provenance apparatus is thorough for a scientific project. There is a CITATION.cff and a CITATION.md alongside the README's request that you cite the eLife article, an AUTHORS file, a CONTRIBUTORS file, a versions.md, a .git_archival.txt for reproducible archive tarballs, and a MANIFEST.in. The code of conduct is the Contributor Covenant, and the project participates in the Open Neuromorphic collaboration network and in PySimHub.

For a scientific codebase, that combination of citation metadata, archival identifiers and a versioned history is the difference between a result that can be reproduced and one that cannot.

Where Brian2 is the wrong choice

There are three limits, and the first is about what the simulator assumes about your model.

The first is that Brian2 is built for spiking neurons on a clock. That is not a limitation on quality, it is a statement of scope, and it is the right scope for the field it serves. But if your model is not a spiking network, the abstraction is fighting you. A rate-based or continuous-time population model is not what a clock-driven spiking simulator is good at, and the same is true of the training loop in modern machine learning, where the gradient computation and the accelerator matter far more than the equation compiler. For a deep learning workload, a different tool entirely is the right answer.

The second is the environment floor, and it has been moving. NumPy 2 is required, and the pyproject pins numpy>=2.3.0 with requires-python >= 3.13, while the README text still says Python >= 3.12 and NumPy >= 2.0. Cython is also a build-time requirement, and the comment in setup.py says explicitly that no Python fallback is possible, so a machine without a working C compiler cannot install the accelerated path. The SPEC 0 badge for minimum supported dependencies is a good sign, but it is a sign that the floor is explicit and rising, not that it is low.

The third is the licence, and it is the one that catches organisations out. Brian 2 is released under the terms of the CeCILL 2.1 license, and the pyproject records license = 'CECILL-2.1'. CeCILL is a French academic-style licence, a copyleft licence, and it is not MIT, not Apache and not GPL. For a company with a standard open source approval checklist, an unfamiliar licence identifier means a review, and a review that has to be requested rather than checked off in a minute.

The final point is about the cost of the abstraction itself. Because the simulator generates code from the equations you write, there is a layer between your model and the machine, and when a simulation behaves unexpectedly the question is whether the error is in the model, in the integration method, or in the generated code. That is a genuine debugging cost, and the tutorials/ and examples/ directories exist to reduce it. A user who wants to see the exact C++ that runs can compile in standalone mode, and that is the honest answer to the question, but it is more machinery than a script that just runs the equations.

Editorial conclusion

Adopt Brian2 if you are modelling spiking neural networks and want a simulator with a readable equation-based interface that compiles to fast code, and you are comfortable with a scientific Python stack and a CeCILL licence. Do not adopt it for deep learning workloads or for non-spiking models, since the whole design is built around a clock-driven neuron model and event-based spikes. Verify first that the Python version on your machine satisfies the requires-python floor in pyproject.toml, that NumPy is at or above the version the project pins, and that your licence policy accepts CeCILL 2.1, which is a French academic licence rather than MIT or Apache.

Frequently asked questions

Official sources

1. brian-team/brian2 on GitHub
2. Issues
3. Project website
4. README