Docker Compose

Recyclarr has an official Docker image hosted on the following platforms:

Registry	Image Name
Github Container Registry (GHCR)	ghcr.io/recyclarr/recyclarr
Docker Hub	recyclarr/recyclarr

info

This guide refers exclusively to the GHCR image, but all steps apply equally to the Docker Hub image. Adjust the image name as needed.

Docker Compose Example

The examples on this page use docker compose with a docker-compose.yml file, which is the recommended approach for managing container configuration in one place.

warning

The example below should not be used verbatim. Copy and paste it, then make the appropriate changes for your specific use case.

networks:
  recyclarr:
    name: recyclarr
    external: true

services:
  recyclarr:
    image: ghcr.io/recyclarr/recyclarr
    container_name: recyclarr
    user: 1000:1000
    networks: [recyclarr]
    volumes:
      - ./config:/config
    environment:
      - TZ=America/Santiago

Here is a breakdown of the above YAML:

• networks
  Recyclarr needs network access to Sonarr and Radarr instances. How those services are hosted determines the network configuration. This example uses a dedicated Docker bridge network (named recyclarr) shared with those services, allowing Recyclarr to reach them directly without going through a reverse proxy.
• image
  The official Recyclarr image, hosted on Github.
• container_name
  Optional. Prevents Docker Compose from generating a prefixed name like prefix_recyclarr.
• user
  Optional user and group ID for the container process. Recyclarr runs as this UID:GID, and any files it creates in the /config volume are owned by this user and group. Defaults to 1000:1000 if not specified.

Tags

Docker tags represent components of the semantic version number following the format X.Y.Z, where:

• X: Represents a major release containing breaking changes.
• Y: Represents a feature release.
• Z: Represents a bugfix release.

The following table describes the available tags. Using v2.1.2 as an example, the table is sorted by risk in descending order. For maximum stability, use the bottom row. For the latest version (highest risk), use the top row.

Tag	Description
latest	Latest stable release, no matter what, including breaking changes
2	Latest feature and bugfix release; manual update for major releases
2.1	Latest bugfix release; manual update if you want new features
2.1.2	Exact release; no automatic updates

info

All docker tags described here are mutable with the exception of the three-component version number (e.g. 2.1.2 in the table above). A mutable tag is one that may change with each release of Recyclarr.

Edge (Dev) Builds

danger

The edge tag should be considered extremely unstable. It contains unreleased code on the master branch and most likely has bugs.

This tag should not be used just to get the latest features. It is intended for testing new features prior to the next release and should not be run against production instances of Radarr or Sonarr.

Use this tag at your own risk!

A mutable docker tag named edge is available and semantically similar to latest, except it contains the absolute latest code changes on the master branch. This is the most volatile and risky tag. Only use it with full understanding of the consequences.

Configuration

Volumes

• /config
  The default directory for all Recyclarr files: configuration, state, logs, and downloaded resources.

Separating config from data for backups

Recyclarr supports splitting its files into a config directory (user configuration, state) and a data directory (logs, downloaded resources). This lets you back up only the config directory while treating data as disposable.

services:
  recyclarr:
    image: ghcr.io/recyclarr/recyclarr
    container_name: recyclarr
    user: 1000:1000
    environment:
      - TZ=America/Santiago
      - RECYCLARR_CONFIG_DIR=/config
      - RECYCLARR_DATA_DIR=/data
    volumes:
      - ./recyclarr:/config      # back this up
      - recyclarr_data:/data     # ephemeral, no backup needed
volumes:
  recyclarr_data:

With this setup, /config holds user configuration and state (back this up), while /data holds only regenerable files. See File Structure for details on what lives in each directory.

Environment

info

The PUID and PGID environment variables are not supported by the official Recyclarr Docker image. These are not built-in Docker features.

Recyclarr's Docker container is rootless. Use the user property (in Docker Compose) or the --user option (with the Docker CLI) to specify the user and group IDs.

• CRON_SCHEDULE (Default: @daily)
  Standard cron syntax for how often Recyclarr should run (see Cron Mode).

• TZ (Default: UTC)
  The time zone for Recyclarr's local time in the container.

• RECYCLARR_CREATE_CONFIG (Default: false)
  Set to true to have /config/recyclarr.yml created automatically when the container starts. If the file already exists, it will not be recreated.

• RECYCLARR_CONFIG_DIR (Default: /config)
  Override the configuration directory path inside the container. See Environment Variables.

• RECYCLARR_DATA_DIR (Default: same as RECYCLARR_CONFIG_DIR)
  Override the data directory path inside the container for ephemeral files (resources, logs). See Environment Variables.

Modes

The Docker container can operate in one of two modes, documented below.

info

recyclarr.yml does not exist the first time the container runs. An error will occur until the file is either copied manually into the volume or created via recyclarr config create.

Manual Mode

There are two ways to invoke Recyclarr in manual mode:

• Prefer docker exec if:
  • The Recyclarr container is already running
  • Using Unraid OS
• Prefer docker run if:
  • The container is not running

Using Docker Run

When using docker run, the container starts, runs a specified operation, and then exits. This is semantically identical to running Recyclarr directly on the host machine, but without the setup requirements.

The general syntax is:

docker compose run --rm recyclarr [command] [options]

Where:

• [command] is one of the supported Recyclarr commands, such as sync and list.
• [options] are any options/arguments supported by that command (e.g. --log debug, --preview).

Examples:

# Create a default `recyclarr.yml` in the `/config` volume
docker compose run --rm recyclarr config create

# Sync Sonarr with debug logs
docker compose run --rm recyclarr sync sonarr --log debug

# Do a preview (dry run) sync for Radarr
docker compose run --rm recyclarr sync radarr --preview --log debug

tip

The --rm option ensures the container is deleted after it runs. Without it, stopped containers accumulate with each manual invocation.

Using Docker Exec

Using docker exec for manual mode is similar to the previous section, except that it uses an already-running instance of the container to perform actions.

Using Docker Compose, the general syntax is:

docker compose exec recyclarr recyclarr [command] [options]

Or using Docker directly:

docker exec recyclarr recyclarr [command] [options]

Where:

• [command] is one of the supported Recyclarr commands, such as sync and list.
• [options] are any options/arguments supported by that command (e.g. --log debug, --preview).

Examples:

# Create a default `recyclarr.yml` in the `/config` volume (without compose)
docker exec recyclarr recyclarr config create

# Sync Sonarr with debug logs (with compose)
docker compose exec recyclarr recyclarr sync sonarr --log debug

# Do a preview (dry run) sync for Radarr (without compose)
docker exec recyclarr recyclarr sync radarr --preview --log debug

Cron Mode

In this mode, no immediate action is performed. The container remains alive and continuously runs sync at whatever CRON_SCHEDULE is set (default is daily).

To enter Cron Mode, start the container in background mode:

docker compose up -d

Running without any command or options causes the container to use this mode.

Troubleshooting

See the Troubleshooting page.

Advanced Configuration

Read-Only Container

For additional security, the container filesystem can be made read-only. This requires two changes in Docker Compose:

1. Add the read_only: true setting to the service configuration.
2. Mount /tmp (inside the container) to a volume. This path must be writable for Recyclarr to run. Using tmpfs is recommended since these files are temporary by design, and keeping them in memory offers some performance benefits.

Using the example docker-compose.yml from the top of this page, add the following:

services:
  recyclarr:
    image: ghcr.io/recyclarr/recyclarr
    read_only: true # <-- Add this to enable read-only mode
    tmpfs: /tmp # <-- Mount /tmp to a volume
    # ...

Prevent in-container privilege escalation

For additional security, run Recyclarr with --security-opt=no-new-privileges to prevent privilege escalation. This prevents the container from gaining new privileges via setuid and setgid binaries like su and sudo.

Add security_opt: ['no-new-privileges:true'] to the service configuration:

services:
  recyclarr:
    image: ghcr.io/recyclarr/recyclarr
    security_opt: ['no-new-privileges:true'] # Add this line
    # ...