Skip to content

Installation guide

annnet is designed to stay lightweight by default. The base package only requires NumPy, SciPy, Narwhals, and pkg-infra, and everything heavier is exposed as an optional extra.

Requirements

  • Python 3.11+
  • pip for standard installs
  • uv if you want a fast local or development workflow
  • git if you want to install from GitHub

Check your environment:

python --version
pip --version
uv --version
git --version

Install from PyPI

If you just want the core package:

pip install annnet

This gives you the core graph data structure and algorithms without pulling in backend, plotting, storage, or ML dependencies you may never use.

Choose your extras

Install only the extras you need. annnet exposes both single-purpose extras and broader install bundles.

Tabular data backends

Single extras:

pip install "annnet[polars]"
pip install "annnet[pandas]"
pip install "annnet[pyarrow]"
  • polars: Polars, the recommended dataframe backend for annnet tables and annotations
  • pandas: pandas dataframe support
  • pyarrow: Apache Arrow table support and parquet-related tabular workflows

If more than one dataframe backend is installed, annnet has a built-in preference order. You can still choose a backend globally or for graph construction when needed; see the support helper reference.

Graph backends

Single extras:

pip install "annnet[networkx]"
pip install "annnet[igraph]"
pip install "annnet[pyg]"

Bundle:

pip install "annnet[backends]"
  • networkx: interoperability with NetworkX and access to its algorithms
  • igraph: interoperability with python-igraph
  • pyg: PyTorch Geometric support
  • backends: installs the pip-installable graph backends networkx and igraph

annnet also supports graph-tool. graph-tool is not available on PyPI: install it separately with Pixi, conda, or your system package manager.

Plotting backends

Single extras:

pip install "annnet[matplotlib]"
pip install "annnet[pydot]"
pip install "annnet[graphviz]"

Bundle:

pip install "annnet[plot]"
  • matplotlib: plots with Matplotlib
  • pydot: DOT export and plots with pydot
  • graphviz: Python bindings for Graphviz
  • plot: installs all pip-installable plotting backends together

When plot(..., backend="auto") is used, annnet selects the first installed backend in its plotting preference order. You can still choose a plotting backend globally or for individual plotting calls; see the support helper reference.

I/O extras

Single extras:

pip install "annnet[excel]"
pip install "annnet[parquet]"
pip install "annnet[zarr_io]"
pip install "annnet[sbml]"

Bundles:

pip install "annnet[io]"
pip install "annnet[storage]"
pip install "annnet[metabo]"
  • excel: Excel import/export support
  • parquet: Parquet I/O support with pyarrow
  • zarr_io: .annnet storage support with Zarr and numcodecs
  • sbml: SBML parsing support
  • io: broader I/O bundle including pandas, openpyxl, pyarrow, zarr, numcodecs, lxml, and toml
  • storage: storage-oriented subset for parquet/zarr/pandas workflows
  • metabo: metabolomics bundle with SBML, COBRApy, and Graphviz

Other install bundles

pip install "annnet[all]"
  • all: broad pip-installable runtime bundle, excluding non-PyPI dependencies and PyG Use all if you want a batteries-included pip install and do not mind a larger environment.

Install from GitHub with uv

Use this if you want the latest repository version before the next PyPI release:

uv venv
source .venv/bin/activate
uv pip install "git+https://github.com/saezlab/annnet.git"

If you want extras as well, use the package URL in the same way you would use an extra on PyPI, for example:

uv pip install "annnet[all] @ git+https://github.com/saezlab/annnet.git"

Local editable install with uv

For development or documentation work with pip-installable dependencies only, clone the repository and install it in editable mode:

git clone https://github.com/saezlab/annnet.git
cd annnet
uv venv
source .venv/bin/activate
uv pip install -e .

For a fuller local environment:

uv sync --group dev --group tests --group docs

You can also add runtime extras you care about:

uv sync --group dev --group tests
uv pip install -e ".[networkx,igraph,polars,sbml,parquet]"

Run tests with uv

From the repository root:

uv sync --group tests
uv run pytest -vv

Use Pixi for non-pip dependencies

Use Pixi when you want the repository's fuller development environment, especially for dependencies that are not reliably available from PyPI such as graph-tool.

pixi install -e gt
pixi run -e gt test-gt

The Pixi environment:

  • installs annnet editable with the repository test dependency group
  • provides graph-tool from conda-forge
  • is the right path for running tests that depend on non-pip packages

If you want the full test suite inside the Pixi environment, run:

pixi run -e gt test-all

Build and serve the docs

From a repository checkout:

uv sync --group docs
uv run --group docs python -m mkdocs serve --dev-addr 127.0.0.1:8000

Open http://127.0.0.1:8000. This executes the Quickstart and the five Guide notebooks; Tutorials render their saved outputs. For a strict build without the preview server:

uv run --group docs python -m mkdocs build --strict

The site is written to site/. See Contributing to the documentation for faster previews, notebook editing, and the public-site configuration.