Installation

NumberLink provides a Python package (numberlink) and CLI (numberlink-cli).

• Supported Python: 3.10+

1. Install numberlink Package from PyPI

numberlink is available on PyPI and supports Python 3.10+.

Option A - Install with uv (Recommended If Using the Package)

1. Install `uv` from the official website: Install uv.

2. Create and activate a virtual environment:

   # create a .venv in the current folder
   uv venv
   # macOS & Linux
   source .venv/bin/activate
   # Windows (PowerShell)
   .venv\Scripts\activate
   

   If you have multiple Python versions, ensure you use a supported one (3.10+), e.g.:

   uv venv --python 3.14
   

3. Install the package (using uv’s pip interface):

   uv pip install numberlink
   

   To enable the interactive pygame viewer and the human render mode:

   uv pip install "numberlink[human]"
   

   To enable the notebook viewer:

   uv pip install "numberlink[notebook]"
   

Option B - Install with pip

1. Install pip from the official website: Install pip.

2. (Recommended) Create and activate a virtual environment.

   Create a .venv in the current folder:

   python -m venv .venv
   

   Activate the virtual environment:

   # macOS & Linux
   source .venv/bin/activate
   
   # Windows (PowerShell)
   .venv\Scripts\activate
   

   Install the package:

   pip install numberlink
   

   See: pip install command.

   Install the optional pygame dependency when using the interactive viewer or the human render mode:

   pip install "numberlink[human]"
   

   Install the optional notebook dependencies when working in Jupyter or Google Colab:

   pip install "numberlink[notebook]"
   

2. Source install with Pixi (Recommended when Installing from Source)

Pixi is a package management tool that provides fast, reproducible environments with support for Conda and PyPI dependencies. The pixi.toml (pixi.toml on GitHub) and pixi.lock (pixi.lock on GitHub) files define reproducible environments with exact dependency versions.

Installation steps

1. Install Pixi: Follow the official Pixi installation guide.

2. Clone repository:

   git clone https://github.com/misaghsoltani/NumberLink.git
   cd NumberLink
   

3. Enter the default environment (first run performs dependency resolution):

   pixi shell          # or: pixi shell -e default
   # non-interactive solve only:
   pixi install -e default
   

4. Verify installation:

   numberlink-cli --help
   

2.1 Available environments

Pixi environments are defined in the [environments] section of pixi.toml (pixi.toml on GitHub). Each environment includes different feature sets for specific use cases:

Name	Description
default	Core runtime dependencies
notebook	Optional notebook extras (ipywidgets, ipyevents)
human	Optional pygame viewer dependency (pygame-ce)
dev	Development tools: ruff, mypy, pyright, shellcheck
build	Build tools (hatch)
all	Complete development environment (dev, build)
doc	Documentation build tools (Sphinx and helpers)
test	Testing tools: pytest, pytest-cov, nose2, pillow
py314ft	Free-threaded interpreter, no pygame (see below)

Each environment is solved for every entry in [workspace] platforms, which covers linux-64, linux-aarch64, osx-64, osx-arm64, and win-64, plus the linux-64-glibc228 and linux-aarch64-glibc228 variants. Those variants pin the oldest glibc the required wheels support, because numpy publishes manylinux_2_27 and newer wheels while pillow and pyzmq publish manylinux_2_28 wheels.

The py314ft environments (py314ft, py314ft-dev, py314ft-test, py314ft-build, py314ft-doc, py314ft-notebook) use a free-threaded interpreter. They leave pygame-ce out because it publishes no free-threaded wheels, so the interactive viewer is unavailable there while the environment, the vectorized environment, and the notebook viewer all work. Everything in numberlink is pure Python and keeps no shared mutable state, so environment instances can be driven from separate threads. See tests/test_free_threading.py (test_free_threading.py on GitHub) for the concurrency coverage.

Activate an environment:

pixi shell -e dev
pixi shell -e all
pixi shell -e notebook

All environments share the same solve-group (default) for consistent dependency resolution. See Pixi’s environment documentation for more details.

2.2 Development tasks

The dev feature includes predefined tasks for code quality and type checking. Run these commands inside an environment that includes the dev feature:

pixi run -e dev lint       # ruff check --fix
pixi run -e dev ulint      # ruff check --fix --unsafe-fixes
pixi run -e dev format     # ruff format
pixi run -e dev fix        # ruff check --fix --unsafe-fixes followed by ruff format
pixi run -e dev mypy       # mypy type check on 'numberlink/'
pixi run -e dev pyright    # pyright type check on 'numberlink/'
pixi run -e dev format-check  # ruff format --check
pixi run -e dev typecheck     # pyright && mypy numberlink
pixi run -e dev yamllint      # yamllint .
pixi run -e dev shellcheck    # shellcheck on scripts (if present)
pixi run -e dev check         # full checks (ruff, pyright, mypy, yamllint, shellcheck)
pixi run -e dev update-citation  # update citation file (if `scripts/update_citation.sh` exists)

The doc feature contains documentation-related tasks (see pixi.toml). Example commands for building the docs inside the doc environment:

pixi run -e doc docs       # build docs
pixi run -e doc docs-nitpick  # build docs with nitpicky warnings enabled
pixi run -e doc docs-run   # build docs and serve locally (may try to bind port 8000)

2.3 Running the project

pixi run numberlink-cli -h

2.4 Building distributions

Use the build environment for creating distribution packages:

pixi shell -e build
pixi run build   # hatch build -t wheel -t sdist

# Or in a single command:
pixi run -e build build

Alternatively, invoke hatch directly if available in your PATH:

hatch build -t wheel -t sdist

Distribution artifacts will be created in the dist/ directory.

3. PyPI (binary / sdist) install

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
pip install numberlink
numberlink-cli --help

4. Source install with uv

uv is a fast Python package manager and project manager that can replace pip, virtualenv, and other tools. It provides fast dependency resolution and environment management.

Setup steps

1. Install UV: Follow the official UV installation guide.

2. Clone repository:

   git clone https://github.com/misaghsoltani/NumberLink.git
   cd NumberLink
   

3. Install the project:

   # uv will automatically create a virtual environment and install dependencies
   uv sync
   
   # Activate the environment
   source .venv/bin/activate  # Linux/macOS
   # Or on Windows: .venv\Scripts\activate
   

4. Verify installation:

   uv run numberlink-cli --help
   # or after activation (source .venv/bin/activate)
   numberlink-cli --help
   

See uv’s documentation for more usage and features.

5. Conda

Use the provided environment files:

# Default
conda env create -f environment.yml -n numberlink

# Development (adds lint/type tools)
conda env create -f environment_dev.yml -n numberlink_dev

This will install the required packages.

Activate the environment:

conda activate numberlink   # or: conda activate numberlink_dev

Or you can install from source within a Conda environment:

# Editable source install
uv pip install -e . # Using uv
# or
pip install -e . # Using pip

Verify Installation

Check installation:

For package:

python -m pip show numberlink || python -c "import numberlink\nprint(numberlink.__version__)"

For CLI:

numberlink-cli --help

Quick run:

numberlink-cli viewer

The viewer subcommand needs the human extra. Without it the command reports the missing module and the installation hint.

Dependencies

Core Python dependencies (see pixi.toml (pixi.toml on GitHub) or pyproject.toml (pyproject.toml on GitHub)): gymnasium, numpy. The pygame dependency ships with the human extra, and the notebook widgets ship with the notebook extra.