nab

nab generates universal lockfiles for Python projects. Declare your target Python versions and platforms in pyproject.toml, then write one PEP 751 pylock.toml covering them. An installer such as pip installs the dependencies selected for its environment from that file.

nab is written in Python and is experimental. It resolves dependencies and can download artifacts; it does not install packages or manage virtual environments.

Documentation · What nab locks · First universal lock

Install

pipx install nab
nab --version

Or install with uv:

uv tool install nab

nab runs on CPython 3.10 and newer. See installation options.

Example project

Save this as pyproject.toml in a new directory:

[project]
name = "example"
version = "0.1.0"
requires-python = ">=3.12,<3.16"
dependencies = ["requests>=2,<3"]

[tool.nab.matrix]
python = ">=3.12,<3.16"
platforms = ["linux_x86_64", "macos_arm64"]

Generate the lock:

nab lock pyproject.toml

Or use uvx nab lock pyproject.toml without installing nab first. This writes one lock for Python 3.12, 3.13, 3.14 and 3.15 on Linux x86-64 and Apple Silicon macOS.

Install from it in a covered virtual environment with pip 26.1 or newer:

python -m pip install -r pylock.toml

In nab, you choose which Python versions, platforms and interpreter implementations to resolve universally, because explicit is better than implicit. See the tutorial for a walkthrough and target configuration for other targets.

Safer defaults

pip and uv can run a downloaded package's build backend just to discover its dependencies. nab makes remote builds opt-in, reducing code execution during locking.

• Universal locking runs no build backends. Host-specific locking allows local project builds; remote builds need explicit permission, which you can limit to one package or index. See build policy.
• Git sources are blocked until you allow them. Opting in requires allowed schemes and repository prefixes, with full commit pins required by default. See Git sources.
• Direct archive sources require a hash, verified before reading metadata. See archive sources.

These controls apply during locking; your installer may still build a locked source distribution.

Soundness

By default, Nab checks dependencies and artifact compatibility for every environment you declare.

• Nab uses each target's preferred wheel metadata; uv assumes consistent metadata across a release's wheels.
• Nab retains dependency Requires-Python upper bounds at Python-minor granularity, including bounds uv deliberately ignores.
• Nab derives yank permission from active exact pins, including selected transitive pins. Rejected parent versions cannot leave permission behind; uv builds its allowlist from initial inputs and locked versions. See Nab's policy and the spec.

More features

Use requirements and markers to select dependencies by environment, and extras or groups for optional sets. Nab also supports scoped policies and metadata overrides, multiple indexes, workspaces, pinned Git sources and hashed archives. Browse the guides for these workflows.

Policy overrides

Nab uses dependency requirements to select which releases a policy overrides.

Allow a reviewed update during a cooldown

Keep a seven-day cooldown, with an exception for reviewed files of certifi 2026.10.19:

[tool.nab]
uploaded-prior-to = "P7D"

[tool.nab.packages."certifi==2026.10.19"]
uploaded-prior-to = "2026-10-20T02:24:17Z"

The fixed cutoff excludes later uploads of the same version. Other versions keep the global cooldown.

Use an index without upload times

Disable the cutoff only for an internal index that does not publish upload times:

[tool.nab]
uploaded-prior-to = "P7D"

[[tool.nab.indexes]]
name = "pypi"
url = "https://pypi.org/simple/"

[[tool.nab.indexes]]
name = "internal"
url = "https://packages.example.com/simple/"

[tool.nab.index.internal]
uploaded-prior-to = false

See package and index policies.

Performance

Nab checks each target's wheel metadata and honors Python upper bounds by default. These checks can catch incompatible dependencies that uv's optimizations may miss.

Nab resolves afresh to check for package changes. Decision order defaults to stable, so HTTP response timing does not steer pin choices.

Configure these options in nab.toml beside pyproject.toml:

reuse is close to uv's default behavior for an unchanged project: keep the existing lock without looking for package updates.

See distribution policies and lock policies for configuration and restrictions.

Universal lock benchmark

Cold and warm cache timings compare Nab's default and performance settings with uv, Poetry and PDM.

Creating a fresh lock for NumPy, pandas, SciPy, Matplotlib and scikit-learn:

Relocking NumPy, pandas, SciPy, Matplotlib and scikit-learn with unchanged inputs. Saved-lock reuse can be a no-op:

Nab performance uses these settings in nab.toml:

http-backend = "httpx2"
decision-order = "arrival"
dist-policy = "wheel-only"
metadata-policy = "prefer-wheel"
assume-consistent-metadata = true

Existing-lock runs also set lock-policy = "reuse". wheel-only considers prebuilt wheels and excludes source distributions. These settings can be slower when dependencies change.

Libraries

nab also publishes components for other tools:

• nab-resolver: a generic PubGrub resolver with stable public module paths.
• nab-markersets: PEP 508 marker algebra.
• nab-provider: Python packaging policy and resolution logic without I/O.
• nab-index: package-index and source clients with caching.
• nab-project: resolve orchestration, lockfiles and downloads.

The other component APIs are experimental. See how the packages fit together and the CLI walkthrough to explore the code.