Sign in Subscribe
overseerr

The Complete Technical Guide: Migrating from Overseerr to Seerr

The transition from Overseerr to its successor, Seerr, is designed to be a seamless "lift-and-shift" operation. The heavy lifting is handled by an automatic database and configuration migration script.

Vincent

• 4 min read
The Complete Technical Guide: Migrating from Overseerr to Seerr

The transition from Overseerr to its successor, Seerr, is designed to be a seamless "lift-and-shift" operation. The heavy lifting is handled by an automatic database and configuration migration script. However, as with any critical system migration, following a precise, step-by-step procedure is essential for data integrity and a smooth cutover.

This guide provides the exact commands and configuration checks required for a successful migration.

Core Principle: It's an In-Place Data Migration

Seerr is a direct fork and continuation of Overseerr. The migration process does not require exporting/importing a JSON file or manually reconfiguring settings. Your existing Overseerr database (app.db by default) and configuration file (config.yml) are read, converted, and used by the new Seerr binary on first launch.

Phase 1: Pre-Migration Preparation (Non-Negotiable)

1.1. Full System Backup

This is the single most important step. Do not proceed without a verified backup of your entire Overseerr application directory.

Standard Docker/Linux Setup:
Your Overseerr data is typically in a directory mapped to a Docker volume or a host folder (e.g., /opt/overseerr or /path/to/overseerr/config).

# 1. Stop the Overseerr container (prevents data changes during backup)
docker stop overseerr

# 2. Create a timestamped backup archive
tar -czf overseerr-backup-$(date +%Y%m%d-%H%M%S).tar.gz /path/to/your/overseerr/config/

# 3. Verify the archive was created successfully
ls -lh overseerr-backup-*.tar.gz

What's in this backup?

  • app.db (Your SQLite database: all users, requests, media, and settings)
  • config.yml (All application settings, Plex/Jellyfin/Emby connections, notification settings)
  • Log files (/logs/)
  • Any custom scripts or assets

1.2. Identify Your Installation Method

Seerr's team only supports official installation methods. Check your current setup:

  • ✅ Official Docker Image: sctx/overseerr:latest (You will switch to sctx/seerr:latest).
  • ⚠️ Unraid Community Application / Snap / Helm Charts: These are community-maintained and may not be fully compatible or updated for the Seerr fork. The official recommendation is to migrate to the official Docker image for full support and feature parity.

Phase 2: The Migration Execution

2.1. Stop & Remove the Old Container

If you used the official Overseerr Docker image:

# Stop and remove the old container (data persists in the volume/host directory)
docker stop overseerr
docker rm overseerr

Do not delete the volume or host directory! Your data is safe there.

2.2. Launch Seerr with the Official Image

Use the exact same volume mappings and environment variables you used for Overseerr. The key is pointing to the same configuration directory.

docker run -d \
  --name=seerr \
  --restart=unless-stopped \
  -p 5055:5055 \
  -v /path/to/your/overseerr/config:/config \
  -e TIMEZONE=America/New_York \
  -e TZ=America/New_York \
  sctx/seerr:latest

Critical Parameters Explained:

  • -v /path/to/your/overseerr/config:/config: This is the magic line. It tells the new Seerr container to use the exact same directory containing your old app.db and config.yml. Seerr's entrypoint script detects this and triggers the migration.
  • sctx/seerr:latest: Always use the official Seerr Docker image. Do not use the old sctx/overseerr tag.
  • Other -e variables (like TIMEZONE) should match your previous setup.

Phase 3: Post-Launch Verification & Completion

3.1. Monitor the Initial Startup & Migration Logs

The migration happens on the first startup. Watch the logs to confirm success.

# Follow the logs in real-time
docker logs -f seerr

What to look for in the logs:

  1. Database Migration: You should see lines like:
    [Migration] Running database migrations...
    [Migration] Successfully applied migration XXXX...
  2. Config Migration: Look for:
    [Config] Migrating Overseerr config to Seerr format...
    [Config] Successfully migrated configuration.
  3. Final Startup: After migrations, the app will start normally:
    Server listening on port 5055
    Application startup complete.

If logs show errors like "database is locked" or "permission denied," stop the container, ensure no other process is accessing the files (e.g., stop any other Overseerr instance), check permissions (chown -R 1000:1000 /path/to/config), and restart.

3.2. Access the Web UI & Validate

  1. Navigate to http://your-server-ip:5055.
  2. Log in with your existing Overseerr credentials (users are preserved).
  3. Crucially, verify:
    • All users are present.
    • All pending and approved requests are visible.
    • Your Plex/Jellyfin/Emby server connections are intact (test the connection in settings).
    • Notification settings (Telegram, Discord, Email, Webhook) are preserved.
    • Your custom CSS/theme (if any) is applied.

3.3. Clean Up & Update Clients

  1. Update any reverse proxies (Nginx, Apache, Traefik) if you changed the container name or port.
  2. Update any external applications (like the mobile app) to point to the new Seerr instance if the URL changed. The API is compatible, but the base URL might differ.
  3. Once fully validated, you can optionally remove the old backup archive from your server to save space, but keep it in a separate offline location for at least 30 days.

Important Notes & Troubleshooting

  • No Downgrade Path: Migration is one-way. You cannot easily go back from Seerr to Overseerr. This makes the backup from Phase 1 essential.
  • Third-Party Images: If you were on a community-maintained image (Unraid, Snap), the safest path is:
    1. Backup your config directory.
    2. Completely remove the community installation.
    3. Set up a fresh, official Seerr Docker container as shown in 2.2.
    4. The migration should still work as long as the config directory contains the original app.db and config.yml.
  • External Databases (PostgreSQL/MySQL): If you used an external DB, ensure your Seerr container's connection string (DB_CONNECTION, DB_HOST, etc.) points to the same database server and database name. The migration script will detect the existing Overseerr tables and migrate them.
  • "Config migration skipped" message: This is normal if your config.yml is already in the newest format. It means your configuration is already compatible.

Conclusion

Migrating from Overseerr to Seerr is technically an in-place codebase upgrade facilitated by containerization. By backing up your data, switching the Docker image to sctx/seerr:latest, and pointing it at your existing config volume, the automated tools handle the rest. Always prioritize using the official Seerr Docker image to ensure compatibility and receive updates.

For the latest information, always refer to the official documentation: https://docs.seerr.dev/

Disclaimer: This guide is based on the official Seerr migration documentation. Always test a migration in a non-production environment first if possible. Your specific setup (reverse proxy, SSL, external DB) may require additional steps not covered here.