pipcheckpoint

Snapshot the pip package state of your Python environment into a named checkpoint, then restore the environment to that exact state any time by loading the checkpoint back.

This is not a file backup — it captures installed package names/versions (plus environment metadata), so you can roll an environment back to a known good set of packages.

Install

pip install pipcheckpoint

Prefer a direct GitHub install (e.g. unreleased changes)? See INSTALL_FROM_GITHUB.md.

The install registers a pipcheckpoint command on your PATH. The package can also be used as a library (see Library usage).

Requirements

• Python 3.9+
• No third-party dependencies (stdlib only)

Command usage

Checkpoints are stored as JSON files in a default directory, depending on how the tool runs:

• Installed via pip (module): ~/.pipcheckpoint/ (per-user)
• Standalone (pipcheckpoint.py): checkpoints/ next to your working directory, so checkpoints live with the project you are snapshotting

Point at another location with --dir.

Create a checkpoint

pipcheckpoint save my-env

Captures every installed package in the current interpreter (the one the command runs under), with name, version, and whether it was an editable install.

List checkpoints

pipcheckpoint list

Inspect a checkpoint

pipcheckpoint show my-env

Restore a checkpoint (exact-state)

pipcheckpoint load my-env

This:

1. installs/upgrades/downgrades packages to match the checkpoint exactly, and
2. uninstalls any packages that are currently installed but not in the checkpoint.

pip, setuptools, and wheel are never uninstalled. Editable installs in a checkpoint are restored as normal pinned installs (with a warning).

Preview first without touching the environment:

pipcheckpoint load my-env --dry-run

Skip the confirmation prompt:

pipcheckpoint load my-env -y

Delete a checkpoint

pipcheckpoint delete my-env

Run as a module

python -m pipcheckpoint list

Use standalone (no installation)

A single-file, self-contained build lives at the repo root as pipcheckpoint.py. Copy it anywhere and run it with any Python 3.9+ — no pip install needed:

python pipcheckpoint.py save my-env
python pipcheckpoint.py list

It supports the exact same subcommands as the installed command. Regenerate it from the source with python tools/build_standalone.py.

Library usage

The whole API is four functions:

from pipcheckpoint import save_checkpoint, load_checkpoint, list_checkpoints, delete_checkpoint

save_checkpoint("my-env")                 # snapshot current env
plan = load_checkpoint("my-env", dry_run=True)  # preview, nothing changed
load_checkpoint("my-env")                 # restore to that exact state
list_checkpoints()                        # what's saved
delete_checkpoint("my-env")               # remove a checkpoint

save_checkpoint and load_checkpoint take a dir= argument to point at a different checkpoints directory. The default is ~/.pipcheckpoint when used as an installed module, and checkpoints/ in the current directory when run standalone.

Notes

• Always run the command with the same Python interpreter (venv) you want to snapshot/restore. Since the tool is pip-installed, it lives in the target environment.
• The state file records Python version and platform so you can spot environment mismatches when loading.
• Pip commands are invoked as python -m pip ... against the running interpreter.

Development

pip install -e .        # editable install, gets the pipcheckpoint command
pipcheckpoint --version
python tools/build_standalone.py   # regenerate the standalone pipcheckpoint.py