Repository navigation
Upgrading and Versions
This page is a short version of the repository's
Versions, upgrades and uninstalling, which has the
detail. Hairspring is experimental and changes quickly. The commands here were run on macOS with the v0.1-RC1 macOS binary
and a build of main; anything needing Linux x86-64 is marked "not run here".
$ hairspring --version
hairspring 0.1.0 (0ba59f0 2026-11-05)
A current build prints the commit and its date after the version. The v0.1-RC1 pre-release prints only hairspring 0.1.0, so a
bare hairspring 0.1.0 with no commit means the pre-release or another build older than that change. The release notes name
the pre-release's commit: f819c1a, committed on 24 October 2026. A build from a source archive prints (unknown) in place of the
commit. Quote the whole line when you report a problem.
The repository documentation describes main, which is ahead of the pre-release. Comparing each subcommand's --help,
these exist only in builds newer than v0.1-RC1:
-
hairspring gc(the pre-release sayserror: unrecognized subcommand 'gc') -
hairspring serve --trusted-proxy,--organisation,--max-connectionsand--max-replays(the pre-release sayserror: unexpected argument '--trusted-proxy' found, and so on) hairspring test --confirm- the commit and date in
hairspring --version
Only the command line was compared; server and web UI changes are not in that list. To use these, build from source (see Installation).
A newer build migrates a results database in place and silently; an older build then refuses it:
$ hairspring results
error: storage error: database schema version 6 is not supported (expected 5)
(exit status 2). That text was printed by the v0.1-RC1 binary for a copy of a database made by main when main was at
schema 6. main has since moved to schema 8, so the same binary on a database from a current main build gives
database schema version 8 is not supported (expected 5) (derived from the code, not run). The numbers change as schemas are
added; the meaning does not. The database is not damaged: your binary is older than the one that last opened it. Keep using the newer build everywhere that database is used, point the old
binary at a different database with --db (which starts a new, empty set of results), or restore a backup taken beforehand.
The CLI has no downgrade command.
A bundle written by a newer build can record environment fields an older build does not know. A build with this check says so when you replay it, and if the replay does not repeat the failure you get exit 3 instead of "not reproduced". Replay bundles from a newer build with a current build. Builds from before this check cannot warn.
- Back up:
(umask 077; sqlite3 .hairspring/hairspring.db ".backup 'hairspring-backup.db'")(run, and read back withhairspring --db hairspring-backup.db results), or for PostgreSQLpg_dump -h db.internal -U hairspring hairspring > hairspring-backup.sqlwith the password in~/.pgpass(mode 600), not on the command line (not run here). - Stop every server and worker that uses the database. On PostgreSQL, the schema 8 upgrade also needs the first open to be the owner's and a grant for the other roles: see Installation.
- Upgrade the server and all workers together.
- Start the server, then the workers, and check
hairspring --versionon each. - To go back, restore the backup. Anything stored after it is lost.
For running a server see Operate-a-Server.
| What | Default place | Remove with |
|---|---|---|
The hairspring command |
~/.local/bin/hairspring |
rm ~/.local/bin/hairspring |
| Hermit, if installed | ~/.local/share/hairspring/hermit |
rm -rf ~/.local/share/hairspring/hermit |
| Results and bundles |
.hairspring/ in each directory you ran hairspring in |
rm -rf .hairspring |
| Configuration |
hairspring.toml from hairspring init
|
delete it if unwanted |
The installers never use sudo. If you installed the Rust toolchain through Hermit's installer
(--install-toolchain), rustup toolchain uninstall <toolchain> removes it, using the RUST_TOOLCHAIN named in scripts/hermit.pin (not run here). For the Python SDK,
pip uninstall hairspring if you installed it with pip; for the other SDKs remove the dependency from your own project.
For a server or worker set up as in the repository's deploy guide, also stop and remove the systemd units (hairspring and hairspring-worker; not run here). The hairspring system user, /etc/hairspring and /var/lib/hairspring (and /var/lib/hairspring-worker) are yours to keep or remove; nothing here deletes them for you, and the database is in /var/lib/hairspring, so back it up first if you may want the results. For Docker Compose, docker compose down stops the stack and docker compose down -v also deletes the PostgreSQL volume
with all results (not run here).
Understand
- What-is-Hairspring
- Concepts-and-Vocabulary
- How-Deterministic-Simulation-Works
- Sweeps-and-Confirmation
- Limits-and-Honesty
Use
- Installation
- Your-First-Run
- Running-Your-Own-Software
- Guest-SDKs-by-Language
- Examples-Overview
- Hairspring-in-CI
- Operate-a-Server
- Upgrading-and-Versions
- Troubleshooting
Reference