File Structure

This page describes the directory structure used by Recyclarr. Recyclarr separates its files into three root directories:

• A configuration directory for the files you write.
• A state directory for files Recyclarr writes that must persist.
• A data directory for ephemeral files that can be regenerated.

By default, the data directory is the configuration directory itself, and the state directory is its state subdirectory. You can separate them using environment variables for cleaner backup workflows or a read-only configuration directory.

Configuration Directory

The configuration directory holds your YAML configuration and settings. Everything here should be included in backups.

Platform	Default Location
Windows	%APPDATA%\recyclarr
Linux	~/.config/recyclarr
MacOS	~/Library/Application Support/recyclarr
Docker	/config

Override with the RECYCLARR_CONFIG_DIR environment variable.

Contents

<config directory>/
├── recyclarr.yml
├── configs/
├── includes/
├── settings.yml
├── cli.yml
└── state/

• settings.yml: Optional settings for the server. Without it, Recyclarr uses default settings.
• cli.yml: Optional CLI settings.
• state/: The default state directory.

Recyclarr does not create settings.yml, configs/, or includes/. Create them when you need them; none of them has to exist.

State Directory

The state directory holds files that Recyclarr writes and needs to keep. Include it in backups. If you lose it, Recyclarr no longer knows which Sonarr and Radarr resources it created and has to adopt them again by name.

By default, this is the state directory inside the configuration directory. Override it with the RECYCLARR_STATE_DIR environment variable.

Contents

<state directory>/
├── radarr/
├── sonarr/
└── server.db

• radarr/, sonarr/: Sync state for each instance.
• server.db: Sync job history kept by a persistent server.

Data Directory

The data directory holds ephemeral files that Recyclarr can regenerate on its own. These do not need to be backed up.

If RECYCLARR_DATA_DIR is not set, data files are stored in the configuration directory (the default behavior from prior versions).

Contents

<data directory>/
├── resources/
└── logs/
    └── server/

Default YAML Configuration Files

Configuration files may be located in multiple places, each documented in the sections that follow. For all supported locations, the following behavior applies:

• All methods may be used together and all corresponding YAML files will be loaded.
• You don't have to use all locations; you can choose only the ones you want to use.
• If at least one configuration file is not found, it will result in an error.
• All YAML files must have the yml or yaml extension.

File: recyclarr.yml

The default YAML configuration file is named recyclarr.yml and it is always located in the configuration directory (listed above based on platform). Example (using docker path):

/config/recyclarr.yml

You can name it recyclarr.yaml instead, but not both. If both files exist, Recyclarr reports a configuration error.

Directory: configs

You can place any number of configuration YAML files in a subdirectory named configs under the configuration directory. The following requirements must be met:

• All files must have the .yml or .yaml extension in order to be recognized.
• Every YAML file placed here is loaded. This behavior is non-recursive; meaning if you place YAML files in subdirectories under configs/, they will not be loaded.
• The names of the files are unimportant and can be whatever you want.

caution

Include templates should not be placed here; use the includes directory instead.

Include Templates Directory

Local include templates go in a directory named includes under the configuration directory. Any relative paths to include templates will start at this directory.

For example, if I have the following include directive in a configuration file named foo.yml:

include:
  - config: bar/reusable.yml

The expected file structure of my includes directory would be visualized as follows:

.
├── configs/
│   └── foo.yml
└── includes/
    └── bar/
        └── reusable.yml

For more information about include templates, see the respective behaviors page.

caution

Configuration files (non-includes) should not be placed here; use the configs directory for those.