Install & upgrade

TokenJam ships as a Python package on PyPI and a TypeScript SDK on npm. Pick the install that matches what you need. Everything below requires Python ≥ 3.10.

The install matrix

Command	Best for	Notes
pipx install tokenjam	Recommended, all platforms	Isolated venv for the tj CLI; sidesteps PEP 668 on Homebrew Python and Debian/Ubuntu
pip install tokenjam	An existing project venv	Run it inside an activated venv, not against system Python
npx tokenjam	A no-install peek	Shells out to the Python CLI via uvx or pipx run under the hood
uvx tokenjam	A no-install peek with uv	Runs the Python CLI directly; equivalent to uvx --from tokenjam tj

pipx (recommended)

pipx install tokenjam

pipx creates an isolated venv for the tj CLI. It works on macOS with Homebrew Python (which refuses pip install into its managed environment) and on Debian 12+ / Ubuntu 24+, and it won’t pollute your system Python or any project venv.

Don’t have pipx?

Platform	Install
macOS	brew install pipx
Debian / Ubuntu	apt install pipx
Windows	py -m pip install --user pipx
Anywhere else	python3 -m pip install --user pipx

Then run pipx ensurepath so pipx’s bin directory is on your PATH.

pip in a venv

python3 -m venv .venv && source .venv/bin/activate
pip install tokenjam

Use this when you want tj inside an existing project environment. Either path gives you the CLI, the local REST API (tj serve), and every native SDK integration.

npx and uvx

npx tokenjam        # or:  uvx tokenjam

These launch the Python CLI without a persistent install. They need a Python runner (uv or pipx) already present. npx tokenjam runs the thin tokenjam npm wrapper, which finds the first available runner and passes every argument straight through, so npx tokenjam optimize and uvx tokenjam quickstart both work.

Upgrading

pipx upgrade tokenjam          # if you installed via pipx (recommended)
pip install --upgrade tokenjam # if you're in a pip + venv setup

After upgrading:

1. Restart the daemon so it picks up the new code: tj stop && tj serve &
2. Confirm the version: tj --version
3. Run a health check: tj doctor

Database migrations apply automatically on the next tj invocation, so there’s no manual migration step.

PyPI’s CDN occasionally lags a minute or two after a release. If pipx upgrade reports “already at the latest version” but tj --version is older than the releases page, wait a moment and retry.

Verify a fresh install

tj doctor

tj doctor checks config validity, DB connectivity, ingest-secret presence, and daemon health. Exit code 0 means clean, 1 means warnings, and 2 means errors.

To confirm telemetry is actually flowing (not just that setup finished), run tj ping — it emits one labeled test span and reports where it landed.