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.

Overview

Recyclarr is now two programs: a server that runs your syncs, and the recyclarr CLI, which sends commands to a server. What that means for you depends on how you run Recyclarr:

• Docker: There is still one image and one container. The container now runs the server, which stays running and syncs on its own schedule instead of using cron. To run a command yourself, use the CLI included in the image through docker exec, for example docker exec recyclarr recyclarr sync. See Docker: Persistent Server for a v8 compose file and its v9 equivalent.
• Without Docker: You run recyclarr sync and other commands the same way. If you have not set up a server, each command starts a temporary server in the background, uses it, and stops it when the command ends. You do not need to set anything up, but recyclarr-server must stay in the same directory as recyclarr. See Temporary Server and CLI: Server Executable Required.

Your configuration files keep working: the YAML format of recyclarr.yml and the files in configs has not changed. In Docker, you change environment variables in your compose file and move the sync schedule to settings.yml. These changes affect how Recyclarr finds and checks your configuration files:

• Default Files No Longer Created
• Invalid Configuration Stops the Server
• CLI: sync --config Removed

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.

Here is a v8 compose file and the same setup in v9. The sections below explain each change.

Version 8

networks:
  recyclarr:
    name: recyclarr
    external: true

services:
  recyclarr:
    image: ghcr.io/recyclarr/recyclarr:8
    container_name: recyclarr
    user: 1000:1000
    networks: [recyclarr]
    volumes:
      - ./config:/config
    environment:
      - TZ=America/Santiago
      - CRON_SCHEDULE=0 4 * * *
      - RECYCLARR_CREATE_CONFIG=true
      - RECYCLARR_LOG_LEVEL=debug

Version 9

networks:
  recyclarr:
    name: recyclarr
    external: true

services:
  recyclarr:
    image: ghcr.io/recyclarr/recyclarr:9  # <<< CHANGED
    container_name: recyclarr
    restart: unless-stopped  # <<< ADDED
    user: 1000:1000
    networks: [recyclarr]
    volumes:
      - ./config:/config
    environment:
      - TZ=America/Santiago
      - RECYCLARR_API_KEY=${RECYCLARR_API_KEY}  # <<< ADDED
      # CRON_SCHEDULE: moved to settings.yml
      # RECYCLARR_CREATE_CONFIG and RECYCLARR_LOG_LEVEL: removed

Version 9: config/settings.yml

server:
  schedule:
    cron: 0 4 * * *

To upgrade:

1. Add an API key in RECYCLARR_API_KEY.
2. Move the schedule from CRON_SCHEDULE to settings.yml.
3. Remove RECYCLARR_CREATE_CONFIG and RECYCLARR_LOG_LEVEL.
4. Add a restart policy so scheduled syncs keep running.
5. Replace docker compose run commands with docker exec.

API Key Required

The server requires an API key of at least 32 characters 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 or a Compose secret. 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.

edge Tag Replaced by Dev Images

The edge tag is no longer updated on Docker Hub or GHCR. The existing edge images stay where they are but get no new builds. The latest unreleased code is now in the master dev image, published to GHCR only:

services:
  recyclarr:
    # <<< CHANGED from ghcr.io/recyclarr/recyclarr:edge
    image: ghcr.io/recyclarr/recyclarr-dev:master

Dev images are just as unstable as edge was. See Dev Builds for branch tags, digest pins, and how long old builds are kept.

Default Files No Longer Created

Recyclarr no longer creates the configs and includes subdirectories or an empty settings.yml. A missing directory or settings file is not an error: without settings.yml, Recyclarr uses default settings. Create these yourself when you need them. Existing files and directories keep working as before.

By default, the state and data directories are inside the configuration directory, so Recyclarr still creates it when it is missing. To leave the configuration directory untouched, for example to mount it read-only, move both directories out of it with the new RECYCLARR_STATE_DIR variable and RECYCLARR_DATA_DIR. See File Structure.

If your configuration directory still has cache or repo folders from an older version, start Recyclarr once with it writable so its migrations can move or delete them. You can also delete the folders yourself. Otherwise, startup fails on a read-only mount.

You can reuse your old v8 configuration volume as the new state directory, for example as the state volume of the Helm chart. v8 kept state in a state folder inside that volume, so the server moves its contents up to the root of the state directory when it starts. Recyclarr does not delete the other files on the volume, such as old configs, settings.yml, and logs. It logs a warning that lists them so you can delete them yourself.

Invalid Configuration Stops the Server

Previously, when a configuration file had errors, Recyclarr reported them and still synced the instances in your other files. Now the server checks your configuration files when it starts, and an error in any of them stops it from starting. Fix every error the server logs, then start it again. See Client and Server.

Log Files and Console Format

Log files moved from logs/cli/ to logs/server/ in the data directory. The CLI no longer writes log files; the server writes them instead. Use --log on CLI commands to show log output on the console.

When its output is not a terminal, as with docker logs, the server now writes one JSON object per line instead of text. To keep text output, set server.logging.format in settings.yml:

# settings.yml
server:
  logging:
    format: text

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 list local Removed

The recyclarr config list local command has been removed. The server loads every configuration file in its default locations, so there is no separate list of local files to check. Remove any calls to recyclarr config list local from your scripts.

recyclarr config create and recyclarr config list templates keep their syntax. Recyclarr now generates their templates from the TRaSH Guides instead of downloading the config-templates repository.

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:

Adopted Custom Format '3D' (b8cd450cbfa689c0259a01d9e29ba3d6) from service ID 66

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.