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)¶

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

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

Install the package (using uv’s pip interface):
```
uv pip install numberlink
```
To enable the notebook viewer:
```
uv pip install "numberlink[notebook]"
```

Option B - Install with pip ¶

Install pip from the official website: Install pip.
(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 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¶

Install Pixi: Follow the official Pixi installation guide.

Clone repository:

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

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

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

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)
dev	Development tools: ruff, mypy, pyright, shellcheck
build	Build tools (hatch)
all	Complete development environment (dev, build)
glibc217	All features with glibc 2.17 compatibility
doc	Documentation build tools (Sphinx and helpers)
test	Testing tools: pytest, pytest-cov, nose2, pillow

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¶

Install UV: Follow the official UV installation guide.

Clone repository:

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

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

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

Dependencies¶

Core Python dependencies (see pixi.toml (pixi.toml on GitHub) or pyproject.toml (pyproject.toml on GitHub)): gymnasium, numpy, pygame.