Skip to main content

File Structure

This page describes the directory structure used by Recyclarr. Recyclarr separates its files into two root directories: a configuration directory for user data that should be backed up, and a data directory for ephemeral files that can be regenerated.

By default, both directories point to the same location. You can separate them using environment variables for cleaner backup workflows.

Configuration Directory​

The configuration directory holds user configuration and state. Everything here should be included in backups.

PlatformDefault 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
└── state/

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/
    └── cli/

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

Directory: configs​

Under the configuration directory, there is a subdirectory named configs in which you can place any number of configuration YAML files. This system works especially well in Docker, where you don't really have an easy way to specify custom CLI arguments. The following requirements must be met:

  • All files must have the .yml or .yaml extension in order to be recognized.
  • Every single YAML file placed here will be loaded as if every file were specified in the --config command line argument. 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​

A directory named includes exists under the configuration directory where local include templates may be placed. 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.