Installation¶

This page covers how to set up PASSAGE on your machine, install dependencies, and configure credentials for Hugging Face uploads.

System Requirements¶

sudo apt install -y libgl1

Install with uv (Recommended)¶

uv is a fast Python package manager. With the repository's uv.lock file, it installs the exact locked versions. The source checkout requires access to the PASSAGE repository:

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/ThalesGroup/passage.git
cd passage

# Install the locked runtime environment (passage and passage-eval)
uv sync --frozen

The standard installation supports CPU evaluation and does not install PyTorch, CUDA, TensorRT, or NVIDIA packages.

Run the tools with uv run --frozen passage …, or activate the environment (source .venv/bin/activate) and call passage directly. This guide uses the short form.

Generation and publication workflows that produce provenance receipts require this cloned repository, installed with uv sync --frozen or pip install -e .. Keep src/passage/, src/passage-eval/, pyproject.toml and uv.lock in place so the receipts can identify the producer code and locked environment. Wheel installations support loading datasets and running passage-eval.

Preview the Documentation Site¶

The documentation site is built with MkDocs Material. To expose it only on your local machine:

make docs-serve

Then open http://127.0.0.1:8000/passage/.

To build the static site into public/, run:

make pages-local

Install with pip¶

From the cloned repository root, if you prefer the standard Python toolchain:

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in editable mode (passage and passage-eval)
pip install -e .

# (Optional) Add the test and lint tools (pip 25.1 or later)
pip install --group dev

The development tools are a dependency group, not an extra, so pip install -e ".[dev]" does not install them. pip resolves versions on its own; use uv sync --frozen to reproduce the locked environment.

Optional PyTorch and edge runtimes¶

If your planner needs PyTorch on CPU, choose CPU in the PyTorch installation selector and install that build in the planner's environment. The optional torch extra can pull NVIDIA packages on Linux and should only be selected in an environment where those dependencies are wanted.

For accelerator execution, obtain compatible vendor drivers and SDKs under their own terms and configure the planner or benchmark for the target device. PASSAGE provides text recipes and dependency locks for edge reconstruction. The operator obtains the build inputs and builds the image locally.

Verify Installation¶

# Check the CLI is available
passage --help

You should see ten subcommands:

The evaluator has its own command, passage-eval --help.

Configure Hugging Face Credentials¶

The upload command can publish your prepared export tree directly to the Hugging Face Hub. Use a token with write access to your destination repository. Set HF_TOKEN in the environment or in .env.secret at the repository root; .env.secret.template shows the format. By default it targets thalesgroup/passage, so pass --repo-id to publish to your own repository.

In .env.secret:

HF_TOKEN=hf_XXXXXXXXXXXXXXXXXXXXXXXX

See Upload for how to choose a destination and custom credential files when the export is ready.

Project Structure¶

After cloning, the repository is organized as follows:

passage/
├── config/
│   └── config.yaml           # Configuration that built PASSAGE v1.0
├── src/
│   ├── passage/              # Generator and release tools
│   │   ├── __init__.py       # CLI entry point
│   │   ├── download.py       # Archive download and receipts
│   │   ├── calibrate.py      # Elevation range and tile inventory
│   │   ├── generate.py       # The generate command and shared helpers
│   │   ├── reference.py      # Exact float64 A* reference solver
│   │   ├── export.py         # compress, export and upload
│   │   ├── regenerate.py     # Bounded, resumable full-release run
│   │   ├── dataset.py        # DatasetSource loader for released data
│   │   ├── obstacles.py      # Superellipse obstacles
│   │   └── ...               # Release generator, audit, qualification, plotting
│   └── passage-eval/         # Evaluator, imported as passage_eval
├── tests/                    # Test suite; evaluator tests in tests/passage_eval/
├── notebooks/                # Notebook sources and per-resolution templates
├── assets/                   # Banner, sample images, hold-out mask
├── scripts/                  # Install and documentation helpers
├── docs/                     # Documentation site source
├── outputs/                  # Generated files (ignored by git)
├── mkdocs.yml                # Documentation site configuration
├── pyproject.toml            # Project metadata and dependencies
└── uv.lock                   # Locked dependency versions

Optional: use passage-eval¶

The evaluation contract, passage-eval (imported as passage_eval), ships in the same passage distribution; its source is in src/passage-eval/. The installs above already include it. It computes the PASSAGE primary metrics, the statistical-discipline rules, trustworthiness diagnostics and deployment-footprint utilities for a planner. You do not need it to generate the dataset — only to score a planner on it.

Sanity check:

uv run --frozen python -c "import passage_eval; print(passage_eval.__version__)"
# -> 1.0.0

# Evaluator tests
uv run --frozen --group dev pytest tests/passage_eval -q

The walkthrough of the public API — scoring, paired bootstrap, three-seed aggregation and the pairwise decision rule — is at Benchmark / passage-eval.

Next Step¶

Once installed, proceed to Step 1 — Download Tiles to begin acquiring satellite elevation data.