Skip to content

Installation guide

annnet is designed to stay lightweight by default. The base package only requires numpy, scipy, and narwhals, and everything heavier is exposed as an optional extra.

Requirements

  • Python 3.10+
  • 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: recommended dataframe backend for annnet tables and annotations
  • pandas: pandas-native dataframe support
  • pyarrow: 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 and access to NetworkX algorithms
  • igraph: interoperability with python-igraph
  • pyg: PyTorch Geometric support
  • backends: installs the pip-installable graph backends networkx and igraph

graph-tool is supported by the codebase, but it is not published on PyPI, so it must be installed 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: plotting support for matplotlib-based rendering
  • pydot: DOT export and pydot-based rendering
  • graphviz: Python Graphviz bindings
  • 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 via 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-oriented bundle with SBML, COBRA, 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 with uv

This repository defines a dedicated docs dependency group for MkDocs:

uv sync --group docs
uv run python -m mkdocs serve

For a one-off strict build:

uv run python -m mkdocs build --strict

The generated site is written to site/.