Skip to content

Install

Protocolith needs Python 3.11 to 3.15 and nothing else: the package has no required dependencies, no compiled code and no network access. It runs headless on macOS, Linux and Windows.

Status of the packages

Route State
From a source checkout with uv sync Works today.
pip install protocolith Available from 0.6.0.
conda-forge Planned, no date.

From source, per operating system

Install uv once, then clone and sync. uv sync creates .venv inside the checkout.

OS Get uv Activate the environment
macOS brew install uv or the installer from the uv documentation source .venv/bin/activate
Linux the installer from the uv documentation, or your package manager source .venv/bin/activate
Windows (PowerShell) winget install astral-sh.uv or the installer from the uv documentation .venv\Scripts\Activate.ps1
Windows (cmd) same .venv\Scripts\activate.bat
git clone https://github.com/protocolith/protocolith.git
cd protocolith
uv sync
uv run protocolith --version

Without uv, any Python 3.11 to 3.15 works:

python -m venv .venv
. .venv/bin/activate            # Windows: .venv\Scripts\Activate.ps1
pip install -e .
protocolith --version

uv sync --extra dev adds the test tools (pytest, ruff and others) used in testing.

The two program names

protocolith and plith are the same program.

What works where

Feature macOS Linux Windows
freeze, record, deviation, verify-ledger, issue, log, head, repair yes yes yes
MCP server on stdio yes yes yes
Append lock fcntl.flock fcntl.flock msvcrt.locking

The two lock modules each run only on their own platform; the project CI runs the tests on Linux, Windows and macOS (see .github/workflows/tests.yml). Newlines in the ledger are always \n, on Windows too.

Check the install

protocolith --version
protocolith freeze --help

Then continue with your first record.

Older card commands

The package still contains the evidence-card tools of earlier releases (validate-card, inspect, hash, doctor, validate-all and others). Some need a repository clone because they read cards and runner scripts that are not part of the package; see the command reference and the archive.