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

The installation guide here will refer exclusively to the image on Github, but all the steps are equally valid for the image on Docker Hub as well. Simply adjust the image name to pull it from where you prefer.

Docker Compose Example

Before we get into the details of how to use the Docker image, I want to start with an example. I personally hardly ever run docker commands directly. Instead, I use docker compose mainly because the docker-compose.yml file is a fantastic way to keep configuration details in one place. Thus, for the remainder of this page, all instruction and advice will be based on the example YAML below. I highly recommend you set up your own docker-compose.yml this way.

caution

The below example should not be used verbatim. It's meant for example purposes only. Copy & paste it but make the appropriate and necessary changes to it 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
  You are going to ultimately want Recyclarr to be able to connect to your Sonarr and Radarr instances. How you have Radarr and Sonarr hosted on your system will greatly impact how this part gets set up. In my case, I have a dedicated docker bridge network (in this example, named recyclarr) for those services. Naturally, that means I want Recyclarr to also run on that bridge network so it can access those services without going out and back in through my reverse proxy.
• image
  The official Recyclarr image, hosted on Github.
• container_name
  Optional, but I don't want the funky prefix_recyclarr name that Docker Compose uses for services by default.
• user
  Optional User and Group ID you want to run the container as. Recyclarr will run using this UID:GID and any files it creates in your /config volume will also be owned by this user and group. The default for this, if not specified, is 1000:1000.

Tags

A series of docker tags are provided which represent various components of the semantic version number following the format of X.Y.Z, where:

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

The structure of the tags are described by the following table. Assume for example purposes we're talking about v2.1.2. The table is sorted by risk in descending order. In other words, if you value stability the most, you want the bottom row. If you value being on the latest version (highest risk), you want 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 and prerelease tags should be considered extremely unstable. These tags contain unreleased code on the master branch and most likely have bugs.

These tags should not be a general recommendation to folks just to get the latest features. They are intended for people that wish to help test new features prior to the next release. These builds should not be run against your production instances of Radarr or Sonarr.

Use these tags at your own risk!

Users that wish to be on the bleeding edge have several options available to them.

The edge Tag

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 considered the most volatile and risky tag. You should only use this tag if you full understand the consequences.

Prerelease Tags

If you prefer immutable docker tags (i.e. you want to explicitly upgrade) but still want unreleased changes, then the prerelease tags are for you. These are in the format of X.Y.Z-dev.N, where:

• X.Y.Z is the next (unreleased) semantic version of Recyclarr. This value changes depending on commits made to the master branch.
• -dev. is a fixed prerelease string indicating that this is a dev build.
• N is a build number, used mainly to identify unique dev builds when they share an identical semantic version number.

Using the table at the start of the Tags section, an example might be 2.1.3-dev.50 where 2.1.3 is the current next version after 2.1.2.

caution

Prerelease tags do not live indefinitely. An unspecified retention period is applied to them, meaning that these tags are permanently deleted from upstream docker registries after that period of time.

These tags are not intended for long-term use. The exact retention details are not documented here since they may change at any time.

Configuration

Volumes

• /config
  This is the application data directory for Recyclarr. In this directory, files like recyclarr.yml and settings.yml exist, as well as logs, cache, and other directories.

Environment

info

The PUID and PGID environment variables are not utilized by the official Docker image for Recyclarr. Many people think these two environment variables are built into Docker, but they are not.

Recyclarr's docker container is rootless. You must use the user property (in your docker compose) or the --user option (with the docker cli) to specify the user and group IDs that Recyclarr runs as.

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

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

• RECYCLARR_CREATE_CONFIG (Default: false)
  Set to true if you want /config/recyclarr.yml to be created for you automatically when the container starts. If the file already exists, it will not create the file again.

Modes

The docker container can operate in one of two different ways, which are documented below.

info

recyclarr.yml does not exist the first time you run the container. You will get an error until you either copy it manually into the volume or run recyclarr config create manually.

Manual Mode

There are two ways to invoke Recyclarr in manual mode. Both work equally well, but you may consider one or the other depending on the following:

• Prefer docker exec if:
  • The Recyclarr container is already running
  • You're using Unraid OS
• Prefer docker run if:
  • The container is not running

See the respective sections below for whichever mode you wish to use.

Using Docker Run

When using docker run to invoke Recyclarr in manual mode, the container starts up, runs a user-specified operation, and then exits. This is semantically identical to running Recyclarr directly on your host machine, but without all of the set up 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. --debug, --preview).

Examples:

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

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

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

tip

The --rm option ensures the container is deleted after it runs (without it, your list of stopped containers will start to grow the more often you run it manually).

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 if you prefer to use 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. --debug, --preview).

Examples:

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

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

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

Cron Mode

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

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

docker compose up -d

This runs it without any command or options, which will result in this mode being used.

Troubleshooting

See the Troubleshooting page.

Advanced Configuration

Read-Only Container

For additional security, you may make your Recyclarr container's filesystem read only. To do this in Docker Compose, you need to make two changes.

1. Add the read_only: true setting to your service configuration.
2. Mount /tmp (inside the container) to a volume. This must be done because this path must be writable for Recyclarr to run. I recommend you use tmpfs for this since the files located at this path are temporary by design and keeping everything in memory offers some performance benefits.

Using the example docker-compose.yml presented at the start of this page, make the following modification:

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