Install¶

Punix v2 is pre-release. There is no pip install punix (yet); you install from source. uv is the supported package manager — everything assumes uv is on your PATH.

Prerequisites¶

Python 3.13 or 3.14. The CI matrix tests both; earlier versions are not supported.
uv ≥ 0.5. Install via curl -LsSf https://astral.sh/uv/install.sh | sh or brew install uv.
POSIX shell + coreutils (mkdir, cp, mv, ln, rm). Standard on Linux and macOS.
For SSH deploys: ssh + rsync (any reasonably recent OpenSSH).
For multi-arch source builds: curl or wget (the fetcher uses a curl-class User-Agent; browser UAs hit anti-AI gateways).

Install¶

git clone https://github.com/fermigier/punix-v2.git  # adjust to your fork
cd punix-v2
uv sync

uv sync resolves the dependency graph (including the pinned MIXINv2 git source) and creates a .venv. After that, uv run punix --help works.

Run without activating the venv

Prefix every command with uv run:

uv run punix check stack.pcl
uv run punix build stack.pcl
uv run punix service deploy MyStack --file stack.pcl

Or activate it once:

source .venv/bin/activate
punix --help

Verify¶

uv run punix --help

You should see the top-level command list:

Usage: punix COMMAND

Punix v2 — typed declarative build & service deployer.

Commands:
  build       Check + build-closure pre-pass, then realise every package module.
  check       Type-check FILE only.
  help        Show the help overview, or a focused help page for TOPIC.
  info        Show recipe metadata and the predicted store path for MODULE.
  install     Build MODULE (cache-hit if already built) and link binaries into the profile.
  list        List installed packages.
  migrate     Migrate a Homebrew formula tree to a mirrored tree of PCL files.
  profile     Inspect and switch the active user profile (list/switch/diff).
  search      Search packages whose pname or description matches REGEX.
  service     Deploy and roll back service stacks (atomic via single os.replace).
  store       Content-addressed store queries.
  uninstall   Remove module from the active profile.
  upgrade     Report newer upstream versions for packages with meta.upstream.
  why         Print TARGET's resolved value and its provenance chain.

If you get command not found, your shell can't see uv's virtualenv — use uv run punix --help instead.

Run the test suite (optional)¶

Before relying on Punix, confirm the conformance suite passes on your box:

make test         # uv run pytest
make check        # ruff + ty + pyrefly + mypy
nox -s tests      # the full matrix (3.13 + 3.14)

You should see 583 passed (the count grows as more conformance tests land). All tests/c_e2e/test_conformance_stage*.py should be green — they're the executable spec.

SSH-only: localhost sshd fixture¶

The SSH e2e tests spin up a real sshd on a free port. They auto-skip if sshd / ssh-keygen aren't on PATH. On macOS /usr/sbin/sshd ships with the OS; on Linux:

sudo apt install openssh-server   # Debian/Ubuntu
sudo dnf install openssh-server   # Fedora

No daemon needs to be running — the fixture starts its own per-test.

Common install issues¶

uv sync fails resolving mixinv2

MIXINv2 is pulled as a pinned git source. If the resolver can't reach GitHub, check your network. The pin lives in pyproject.toml:

[tool.uv.sources]
mixinv2 = { git = "https://github.com/Atry/MIXINv2",
            rev = "f09af5ba277e124cbd139322a2db9301fd97d394",
            subdirectory = "packages/mixinv2" }

Python 3.12 or earlier

Not supported. Punix uses 3.13-specific typing features (PEP 695 type statement, TypeAliasType). Upgrade or use uv's --python flag: uv sync --python 3.13.

macOS BSD vs GNU coreutils

Punix targets POSIX, not GNU. macOS mv, ln, cp all work. The one place that bit us historically was mv -T (GNU-only) for the atomic symlink flip — now removed (see decisions).

Next¶

→ Your first build: a single-package PCL module, realised into the content-addressed store.