Environment Variables

These environment variables control the behavior of the Recyclarr CLI and server.

Looking for config substitution?

To substitute environment variable values into your YAML configuration files, see Value Substitution.

RECYCLARR_CONFIG_DIR

Overrides the default configuration directory location. This directory holds the files you write, such as recyclarr.yml and settings.yml. See File Structure for platform defaults and directory contents.

export RECYCLARR_CONFIG_DIR="/custom/path/to/config"

When you set both RECYCLARR_DATA_DIR and RECYCLARR_STATE_DIR to paths outside the config directory, Recyclarr only reads from it, so you can mount it read-only (for example, from a Kubernetes ConfigMap). The exception is leftover cache or repo folders from older versions, which startup migrations move or delete. Start once with the directory writable, or delete those folders, before you mount it read-only.

RECYCLARR_DATA_DIR

Overrides the location for ephemeral data directory used for regenerable files like downloaded resources and logs.

export RECYCLARR_DATA_DIR="/custom/path/to/data"

If unset or empty, defaults to the same path as RECYCLARR_CONFIG_DIR. Relative paths are resolved from the config directory.

RECYCLARR_STATE_DIR

Overrides the location of the state directory, which holds sync state and the server's job history. This directory must persist and be backed up: if you lose it, Recyclarr loses track of which Sonarr and Radarr resources it manages.

export RECYCLARR_STATE_DIR="/custom/path/to/state"

If unset or empty, defaults to state inside the config directory. Relative paths are resolved from the config directory.

This example keeps the config directory read-only and gives each kind of file its own location:

export RECYCLARR_CONFIG_DIR="/config"  # can be read-only
export RECYCLARR_DATA_DIR="/data"      # can be ephemeral
export RECYCLARR_STATE_DIR="/state"    # must persist

RECYCLARR_SERVER_URL

The address of a running Recyclarr server for CLI commands to use. When set to a non-empty value, it overrides server.base_url in cli.yml.

export RECYCLARR_SERVER_URL="http://localhost:7982"

The Docker image sets this variable so that docker exec commands use the container's server.

RECYCLARR_API_KEY

The server API key. Both programs read it:

• The server requires a key of at least 32 characters from this variable or from RECYCLARR_API_KEY_FILE, and does not start without one. A temporary server gets a one-time key from the CLI instead, so you only set this for a persistent server.
• The CLI sends it to the server at server.base_url. When set to a non-empty value, it overrides server.api_key in cli.yml.

export RECYCLARR_API_KEY="$(openssl rand -hex 32)"

The Docker image has no default for this variable. Set it on the container; the server and docker exec commands both use it.

RECYCLARR_API_KEY_FILE

The path of a file that contains the server API key, such as a Docker Compose secret or a Kubernetes Secret volume. Use it instead of RECYCLARR_API_KEY to keep the key out of the environment. Both programs read it the same way they read RECYCLARR_API_KEY, and trailing line breaks in the file are ignored.

export RECYCLARR_API_KEY_FILE="/run/secrets/recyclarr_api_key"

Set only one of RECYCLARR_API_KEY and RECYCLARR_API_KEY_FILE; setting both is an error. The server reads the file again on every request, so you can rotate the key without a restart.

OTEL_*

The standard OpenTelemetry variables. Setting OTEL_EXPORTER_OTLP_ENDPOINT makes the server export traces, metrics, and logs to an OpenTelemetry Collector or another OTLP receiver. See OpenTelemetry for the variables Recyclarr uses.

export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"

NO_COLOR

Disables ANSI color output when set to any non-empty value.

export NO_COLOR=1

Useful for scripting, piping output to files, or terminals that don't support colors.

See no-color.org for more information about this standard convention.