`pdk pins`¶

pdk pins finds version declarations across a project and moves the selected package versions together while preserving each declaration's existing operator. With no options it prompts once per managed package and offers the combination tested with the installed Prodockit release.

Use the version maintenance task guide when evaluating an upgrade or comparing generated output.

Pins uses the shared decision and field language, although its shorter report does not need the complete phase-and-activity frame.

Synopsis¶

Use interactive selection, read-only checking, or explicit version assignments.

pdk pins [OPTIONS]
pdk pins --check --offline
pdk pins --set PACKAGE=VERSION [--set PACKAGE=VERSION ...]

Working directory¶

Run Pins from the project root so it can find every declaration in the workflows, requirements files, toolchain file, and Python version file. Use --root PATH when deliberately managing a different project.

Pins changes declarations, not installed packages. If the project has a .venv but another interpreter is running, Pins warns before proceeding: its tested defaults come from the running Prodockit release.

From an unrelated directory, Pins usually does not fail: it reports not declared anywhere for each package and ends with No version declarations found. Nothing to do. That means the directory is wrong; it does not mean the project has no versions to maintain.

Options¶

Table 39.1 lists package-selection and check controls.

1. Pins options

Option	Behaviour
`-r`, `--root PATH`	Scan another project root; defaults to the current directory.
`-p`, `--package NAME`	Manage one package; repeat to select several.
`--set PACKAGE=VERSION`	Set an explicit version without prompting; repeatable and implies `--no-input`.
`--latest`	Select the newest PyPI release for every managed package without prompting.
`--no-input`	Never prompt; update only packages already selected by `--set` or `--latest`.
`--check`	Report drift or disagreement and write nothing.
`--offline`	Skip PyPI and use only declarations plus Prodockit's tested combination.
`-h`, `--help`	Show installed help and exit.

The default managed set is Zensical, WeasyPrint, Prodockit, Markdown, PyMdown Extensions, Pandoc, and Python.

Effects¶

Pins changes only discovered version declarations. A minimum constraint stays a minimum constraint and an exact CI pin stays exact. It does not install the selected software, copy template files, or repair renderer binaries. When a shared-file manifest is present, check mode also reports shared-file drift.

--latest is an explicit decision to move beyond the combination tested with the installed Prodockit release. Rebuild and compare both website and PDF before retaining such a change.

Exit status¶

Normal interactive or set mode exits non-zero on an invalid selection or a file that cannot be updated safely. --check exits non-zero when declarations disagree, a managed release is behind the checked source, or a declared shared file differs.

Use these commands to diagnose, install, or synchronize the selected versions:

pdk diag reports unsupported combinations and points to Pins for the version decision.
pdk adopt installs and aligns the supported project toolchain.
pdk template-sync follows the incoming template's paired Prodockit release before applying template files.

pdk pins¶