Installing NeuroLang#

NeuroLang requires Python ≥ 3.12. The recommended way to install it is with uv — a fast Python package manager — or with standard pip.

NeuroLang is four packages, each built on the ones before it:

nl-expr: the expression engine: typed expressions, pattern-matching walkers and first-order logic;
nl-core: relational algebra, Datalog and probabilistic Datalog;
neurolang: the Datalog and SQUALL languages, the frontends (NeurolangDL, NeurolangPDL) and brain regions;
neurolang-apps: the neurolang-query command line, its interactive mode, the query assistant and the engines of predefined data.

neurolang[apps] installs them all; neurolang alone installs the library without the applications.

Note

pip install neurolang installs the latest release published on PyPI (0.1a21, October 2026), from before the split: one package, with the applications. The commands below install the current master branch from GitHub instead, with the changes listed as Unreleased in the Changelog.

Windows

1. Install uv

Open PowerShell and run:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Or use pip directly if you already have Python installed:

pip install uv

2. Install NeuroLang

uv pip install "neurolang[apps] @ git+https://github.com/NeuroLang/NeuroLang.git#subdirectory=packages/neurolang"

3. Verify

Open a new terminal and run:

python -c "import neurolang; print('NeuroLang installed OK')"

macOS

1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install NeuroLang

uv pip install "neurolang[apps] @ git+https://github.com/NeuroLang/NeuroLang.git#subdirectory=packages/neurolang"

3. Verify

python -c "import neurolang; print('NeuroLang installed OK')"

Linux

1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install NeuroLang

uv pip install "neurolang[apps] @ git+https://github.com/NeuroLang/NeuroLang.git#subdirectory=packages/neurolang"

3. Verify

python -c "import neurolang; print('NeuroLang installed OK')"

From source

Clone the repository and install its four packages in editable mode, in the environment .venv of the clone, with all extras and the development and documentation tools:

git clone https://github.com/NeuroLang/NeuroLang.git
cd NeuroLang
uv sync --all-packages --all-extras --no-extra embeddings

To update your local copy:

git pull
uv sync --all-packages --all-extras --no-extra embeddings

Run Python in that environment with uv run or by activating it (source .venv/bin/activate).

Verify:

python -c "import neurolang; print('NeuroLang installed OK')"

Using pip without uv#

If you prefer plain pip, which does not know that the packages come from the same repository, name the four of them:

pip install \
  "nl-expr @ git+https://github.com/NeuroLang/NeuroLang.git#subdirectory=packages/nl_expr" \
  "nl-core @ git+https://github.com/NeuroLang/NeuroLang.git#subdirectory=packages/nl_core" \
  "neurolang @ git+https://github.com/NeuroLang/NeuroLang.git#subdirectory=packages/neurolang" \
  "neurolang-apps @ git+https://github.com/NeuroLang/NeuroLang.git#subdirectory=packages/neurolang_apps"

Dependencies#

NeuroLang requires the following libraries (installed automatically):

NumPy, SciPy and pandas
nibabel and nilearn for neuroimaging data
PySDD for probabilistic inference through knowledge compilation
Lark for the Datalog and SQUALL parsers
rdflib for ontologies
typing_inspect
for the applications, scikit-learn, matplotlib, PyYAML and pyarrow (for the parquet files of the neurostore engine)

Optional extras#

Extra	Installs	Use it to
`apps`	`neurolang-apps`	use the `neurolang-query` command line and the engines
`tui`	`prompt-toolkit`, `rich`	use the interactive mode of `neurolang-query`
`ras-polars`	`polars`, `pyarrow`	use the Polars relational-algebra backend (see Performance and Configuration)
`dev`	`pytest`, `problog`	run the test suite

For instance, from a clone of the repository:

uv sync --all-packages --extra ras-polars

Alternative backend#

By default NeuroLang stores relations in pandas data frames. One alternative backend is available:

polars: Backed by Polars lazy frames. Install the ras-polars extra. It is usually faster on relations holding numbers and strings; see Performance and Configuration for details.

The former dask (dask-sql) backend has been removed; selecting it raises a ValueError that lists the available backends.

To select a backend, either edit the [RAS] backend entry of packages/nl_expr/nl_expr/config/config.ini, or call

from neurolang.config import config
config.set_query_backend("polars")  # "pandas" or "polars"

at the top of your script, before importing other NeuroLang modules.