The_Great_Archive/ArchiveBox
1
0
Fork 0
mirror of https://github.com/ArchiveBox/ArchiveBox.git synced 2026-09-12 19:50:57 +05:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity
7611a57917
ArchiveBox/docs/Upgrading.md
Nick Sweeting 7611a57917
Preserve complete legacy collections during upgrade
2026-08-01 14:25:57 -07:00

7.3 KiB
Raw Blame History

Upgrading Versions

# Update ArchiveBox using the package manager you originally installed it with
uv tool install --python 3.13 --upgrade 'git+https://github.com/ArchiveBox/ArchiveBox.git@dev'
# or: sudo apt update && sudo apt install --only-upgrade archivebox
# or: brew update && brew upgrade archivebox

cd ~/archivebox/data
archivebox init
archivebox install
archivebox update
archivebox status

# Docker Compose install
cd ~/archivebox
docker compose pull
docker compose run --rm archivebox init
docker compose run --rm archivebox install
docker compose run --rm archivebox update
docker compose up -d

✅ Upgrading checklist:

  1. Find the version you want to upgrade to on https://github.com/ArchiveBox/ArchiveBox/releases
  2. Read the release notes carefully for any instructions or extra steps around upgrading for each release you're skipping or installing
  3. Stop any running ArchiveBox server, scheduler, and worker processes, then make a full backup of your index.sqlite3 and archive/ content before upgrading! gzip -9 < index.sqlite3 > "index.sqlite3.$(date +%s).bak"
  4. Follow the steps below for your installation method, then run archivebox init, archivebox install, and archivebox update inside the collection
  5. Confirm the upgrade succeeded and check for any orphan/corrupted snapshots with archivebox status

💬 Open an issue in our bug tracker if you experience any problems with upgrading/merging/modifying collections.

Note: It's recommended to only upgrade one major version at a time. Follow each intermediate release's upgrade instructions and Python requirements rather than installing old releases with the current Python version. Upgrading directly across multiple major versions may work in some cases, but is not recommended for maximum data safety.

ℹ️ How it works internally:

The same command is used for initializing a new archive and upgrading an existing database. archivebox init is idempotent and can safely be run multiple times; it applies database migrations and prepares collection-level state. archivebox install resolves runtime dependencies for the new version. archivebox update performs filesystem migrations and reconciles Snapshot metadata with the current layout. archivebox status checks collection health afterward.

There are three main areas on disk that ArchiveBox modifies during upgrades:

  • index.sqlite3 contains the SQLite3 DB index that gets upgraded automatically by Django based on the changes in archivebox/core/models.py.
  • archive/users/<user>/snapshots/<date>/<domain>/<uuid>/index.jsonl stores per-Snapshot metadata alongside plugin-namespaced output. archivebox update may rewrite metadata, migrate older layouts, and maintain legacy timestamp compatibility symlinks.
  • Snapshot output directories and plugin paths can move as filesystem schemas evolve, so the entire archive/ tree must be backed up with the database.

ArchiveBox.conf is migrated through the normal config loader/writer when options are renamed or normalized. Back it up with the rest of the collection and review release notes for config changes.

As of v0.4 and above, ArchiveBox uses the Django migrations system for deterministic, atomic, safe upgrades, so your DB should always be left in a consistent state in the event of a failure or power outage. If you need help fixing a corrupted collection, open an issue using the link above.

More info:

Upgrading with Docker Compose ⭐️

Using Docker Compose is recommended because it makes upgrading a breeze! ✨
Pulling and running the latest version automatically upgrades the ArchiveBox collection and all of ArchiveBox's internal dependencies.

cd ~/archivebox        # or wherever your folder containing docker-compose.yml is
docker compose down    # stop the currently running ArchiveBox containers
docker compose pull    # pull the latest image version from Docker Hub
docker compose up      # collection will be automatically upgraded as it starts

More info:

Upgrading with plain Docker

Upgrading with plain Docker is similar to the process with Docker Compose, but you have to run archivebox init manually at the end to finish the process.

docker ps -a -q  --filter ancestor=archivebox/archivebox  # find any currently running archivebox containers
docker stop CONTAINER_ID

docker pull archivebox/archivebox:dev
docker run -v $PWD:/data -it archivebox/archivebox:dev init
docker run -v $PWD:/data -it archivebox/archivebox:dev install
docker run -v $PWD:/data -it archivebox/archivebox:dev update

# restart the archivebox server container if needed
docker run -v $PWD:/data -it -p 8000:8000 archivebox/archivebox:dev server 0.0.0.0:8000

More info:

Upgrading with a package manager

Package manager releases take a lot of effort to maintain (contributions welcome!) and sometimes lag behind the Docker releases. We make a best effort to have the latest release available through all channels within a reasonable timeframe.

cd ~/archivebox/data   # or wherever your data folder is

# upgrade ArchiveBox using the package manager you originally used to install it
uv tool install --python 3.13 --upgrade 'git+https://github.com/ArchiveBox/ArchiveBox.git@dev'
# or
sudo apt update
sudo apt install --only-upgrade archivebox
# or
brew update
brew upgrade archivebox

archivebox init        # run init to upgrade the collection to the latest version
archivebox install     # refresh runtime dependencies if needed

archivebox update       # migrate/reconcile Snapshot files and metadata

archivebox status      # check that everything succeeded

More info:

Merge two or more existing archives

See Merging Collections...


Related Documents