Skip to main content

​
Upgrading from current version

For any upgrade within the 2.x line, schema migrations run automatically on startup. No manual steps are required.
1

Pull the latest image

docker compose pull
2

Restart the container

docker compose up -d
3

Verify startup

Check the logs to confirm migrations completed successfully and Teamarr is running:
docker logs --tail 50 teamarr
That’s all. Teamarr detects schema changes on startup and applies the necessary migrations before the application begins serving requests.

​
Upgrading from legacy 1.x

There is no automatic migration path from 1.x to 2.x. The 2.x release involves significant architectural changes that make in-place migration impossible. Your 1.x database cannot be imported into 2.x.You must choose one of the two options below.

​
Option 1: Start fresh

Archive your old database and set up a clean 2.x instance. Teamarr detects a legacy database on startup and guides you through the process, including downloading a backup of your 1.x data for reference. Update your docker-compose.yml to use the latest tag: 
services:
  teamarr:
    image: ghcr.io/pharaoh-labs/teamarr:latest
    container_name: teamarr
    restart: unless-stopped
    ports:
      - 9195:9195
    volumes:
      - ./data:/app/data
    environment:
      - TZ=America/New_York
Then pull and start: 
docker compose pull
docker compose up -d

​
Option 2: Stay on 1.x

If you’re not ready to migrate, you can continue running the final 1.x release indefinitely by pinning the archived image tag: 
image: ghcr.io/pharaoh-labs/teamarr:1.4.9-archive
The 1.4.9-archive image will continue to function but will not receive updates, bug fixes, or new features.

​
What happens during migration

When Teamarr starts after an upgrade, it:
  1. Connects to teamarr.db (or creates it if it doesn’t exist)
  2. Reads the current schema version from the database
  3. Runs any pending versioned migration blocks to bring the schema up to date
  4. Reconciles the live schema against the expected schema, adding any missing columns
  5. Starts the application
This happens automatically and takes only a few seconds for most upgrades.

​
Backup and restore

Before any major upgrade or configuration change, take a backup from Settings > System > Backup & Restore. Downloading a backup Click Download Backup to save a complete copy of teamarr.db. The backup includes:
  • All teams and their configurations
  • Templates and presets
  • Event groups
  • All settings
Restoring a backup Click Restore Backup and upload a .db file. Teamarr automatically saves a copy of the current database before overwriting it. Restart the application after the restore completes.

​
Database safety

Never delete teamarr.db. This file contains all your configuration — teams, templates, event groups, and settings. It cannot be recreated. Schema upgrades are always handled through non-destructive migrations.
The database file lives at ./data/teamarr.db (mapped from /app/data/teamarr.db inside the container). As long as your ./data volume is intact, your configuration survives any upgrade or container restart.

​
Image tags

TagDescription
latestCurrent stable release. Recommended for most users.
devDevelopment builds from the dev branch. May contain bugs or incomplete features.
1.4.9-archiveFinal 1.x release. No longer maintained — use only if you need to stay on 1.x.

Build docs developers (and LLMs) love

Get started for freeTalk to us