From zero to a running program in five minutes

Dependencies in capa.toml

Projects declare dependencies in a capa.toml at the root. The same file pins the source: a git URL with an exact tag, or a relative path. A signed registry index maps short names to git sources and is GPG-verified before any name is trusted.

[package]
name = "my-project"
version = "0.1.0"
capa = ">=0.8.4"

[dependencies]
capa_log = { git = "https://github.com/nelsonduarte/capa_log", tag = "v0.1.2" }

[dev-dependencies]
capa_test = { git = "https://github.com/nelsonduarte/capa_test", tag = "v0.1.1" }

$ capa install        # resolve, fetch deps into ./vendor/, write capa.lock
$ capa --run main.capa
$ capa install        # idempotent: rerun to refresh against capa.lock

The capa.lock pins the resolved git SHA plus a SHA-256 of the fetched tarball, so installs are bit-reproducible. When a dependency carries a verify_key, capa install verifies the GPG tag signature or Sigstore SLSA attestation before unpacking. Since 1.18.1, a missing gh on your PATH is an error rather than a warning for such a dependency: the verifier being absent no longer downgrades to "install it anyway". CAPA_ALLOW_MISSING_GH=1 overrides, and names on stderr every dependency it let through. Full guide in docs/packages.md.

The compiler floor, and a manifest that will not parse

The capa key above is the oldest compiler the project says it can be built with. Since 1.19.0 it is enforced. Before that it was parsed and ignored, so a floor had never been tested against a running compiler; if your project declares a floor above the compiler you are running, you now get a refusal where you used to get a build:

$ capa --check main.capa
capa: /path/capa.toml: this project declares capa = '>=99.0.0', but the
compiler running the build is 1.27.0.
$ echo $?
1

The policy splits by root versus dependency. The root manifest's floor is a hard error (exit 1). A dependency's floor is a warning naming the package, because you cannot satisfy it by editing a manifest you own; that warning is raised by the commands that compose the dependency graph (--check-capabilities, --compose-sbom, --check-policies), not by a plain --check. A missing capa key constrains nothing. CAPA_IGNORE_CAPA_FLOOR=1 downgrades the refusal to a warning that reprints, in full, the refusal it overrode. Before reaching for it, check whether the floor or the compiler is the thing that is out of date.

The same release stopped the compiler ignoring a capa.toml it could not parse. Any parse error, including one lowercase letter in a capability name, is now a refusal:

$ capa --check main.capa
capa: broken capa.toml: /path/capa.toml: [capabilities].max names unknown
capability(ies): ['stdio']; allowed: ['Clock', 'Db', 'Env', 'Fs', 'Net',
'Proc', 'Random', 'Serve', 'Stdio']
$ echo $?
2

There is deliberately no escape hatch for this half. Ignoring the manifest discards the name-to-directory mapping that makes a declared dependency path authoritative, and on 1.18.1 that was measured compiling an unaudited directory that merely shared the dependency's name, printing ok and exiting 0. Details in the 2026-07-20 advisory.

Seed libraries

The signed registry lists eighteen libraries; the original seed set of eight is below, and the packages page has the full list. Each declares its own capability surface, visible in the SBOM before you read its code. A library marked none declares no capability, so no function in it can perform an effect: the discipline is checked per function, over the code the compiler reads.

Pipeline modes and tooling flags

Each pipeline mode subsumes the previous: --run implies --transpile, which implies --check.

$ capa --check examples/io.capa
OK

$ capa --run examples/grades.capa
=== Roster ===
  Ana: 17.5 (Excellent)
  Bruno: 13.0 (Pass)

Every invocation also works as python -m capa <args> if capa is not on your PATH.

Where to go next