Version 9.0 (Unreleased)

Unreleased

warning

This page tracks deprecations and breaking changes planned for Version 9.0, which is currently in development. The content here may change as features are added, modified, or removed during the development cycle.

Docker: Persistent Server

The Docker image now runs the Recyclarr server instead of a cron job. The server stays running, syncs on a built-in schedule, and accepts commands from the CLI. See the Docker guide for the full setup.

API Key Required

The server requires an API key and does not start without one. The image has no default key. Set RECYCLARR_API_KEY on the container:

services:
  recyclarr:
    image: ghcr.io/recyclarr/recyclarr:9
    environment:
      - TZ=America/Santiago
      - RECYCLARR_API_KEY=${RECYCLARR_API_KEY}  # <<< ADDED

See API Key for how to create the key and store it in a .env file. CLI commands you run with docker exec use the same key automatically.

Schedule Moved to settings.yml

The CRON_SCHEDULE environment variable is no longer read. Remove it from your compose file and put the same cron expression in server.schedule.cron in settings.yml. If you did not set CRON_SCHEDULE, you can skip this step: the new default also syncs once a day at midnight.

services:
  recyclarr:
    image: ghcr.io/recyclarr/recyclarr:9
    environment:
      - TZ=America/Santiago
      - CRON_SCHEDULE=0 4 * * *  # <<< REMOVED

# settings.yml
server:
  schedule:
    cron: 0 4 * * *

Container Arguments No Longer Run the CLI

Arguments after the image name no longer run Recyclarr commands. For example, docker compose run --rm recyclarr sync does not sync anymore. Run commands in the running container with docker exec instead:

docker exec recyclarr recyclarr sync

If an external scheduler ran Recyclarr this way, see Using an External Scheduler.

Removed Environment Variables

Remove these variables from your compose file. Recyclarr ignores them:

• RECYCLARR_CREATE_CONFIG: Create your configuration files in /config yourself.
• RECYCLARR_LOG_LEVEL: Use --log on CLI commands to show log output on the console.

Add a Restart Policy

The container must keep running for scheduled syncs to happen. Add a restart policy so the server starts again after a crash or a reboot:

services:
  recyclarr:
    restart: unless-stopped

To call the HTTP API from outside the container, you also need to publish port 7982. See HTTP API.

CLI: Server Executable Required

The release archives now contain two executables: recyclarr and recyclarr-server. The CLI sends its work to a server and starts recyclarr-server from its own directory when needed. If you copy the recyclarr executable somewhere by hand, copy recyclarr-server to the same directory. See Client and Server.

CLI: sync --config Removed

The -c|--config option of recyclarr sync has been removed. The server loads configuration only from its default locations. Move any configuration files you passed with --config into the configs directory.

recyclarr sync --config ../myconfig.yml # <<< REMOVED

CLI: config Commands Removed

The recyclarr config create, recyclarr config list local, and recyclarr config list templates commands have been removed. To start from a template, copy it from the Quick Setup Templates page into your configuration directory.

CLI: migrate Removed

The recyclarr migrate command has been removed. Migrations already ran automatically, and they now run each time the server starts. Remove any calls to recyclarr migrate from your scripts. See Migration System.

CLI: state repair Removed

The recyclarr state repair command and its --adopt flag have been removed. Sync is now self-healing: when a configured resource matches an existing resource in the service by name but has no state mapping, Recyclarr automatically adopts it and emits a warning:

CF 'CRiT' already existed in the service and was replaced by Recyclarr

Previously, this scenario required running recyclarr state repair --adopt to resolve the conflict. Common situations where this occurred:

• Pointing Recyclarr at an existing Sonarr/Radarr instance with matching resources
• Relocating a service to a new URL (changing base_url)
• Database rebuilds or instance migrations

All of these are now handled automatically during sync.

The only scenario that still requires manual intervention is ambiguous matches: when 2+ service resources share the same name (case-insensitive), Recyclarr cannot determine which one to adopt. The error message instructs you to resolve the duplicates in the service directly.

New Mental Model

If it's in your config, Recyclarr owns it. If you want to manually manage a resource, remove it from your config. Recyclarr warns you when it adopts something that already existed, giving you a chance to notice and adjust your config if needed.