Linux (systemd)

This guide sets up the Recyclarr server as a systemd service on Linux distributions such as Ubuntu, Debian, and Fedora. systemd starts the server at boot and starts it again if it fails. The server then syncs on its built-in schedule and accepts commands from the CLI.

Before you start, install Recyclarr with the manual installation steps. The steps on this page expect both executables, recyclarr and recyclarr-server, in /usr/local/bin.

Create a Service User

Run the server as its own system user instead of your login account. This command creates a user named recyclarr with /var/lib/recyclarr as its home directory:

sudo useradd --system --create-home --home-dir /var/lib/recyclarr \
  --shell /usr/sbin/nologin recyclarr

The service uses /var/lib/recyclarr as its configuration directory. Your YAML configuration, settings.yml, sync state, logs, and downloaded resources all go there.

Add Your Configuration

Create your YAML configuration in /var/lib/recyclarr. Edit files as the recyclarr user so that the server can read them:

sudoedit -u recyclarr /var/lib/recyclarr/recyclarr.yml

See Getting Started for what to put in the file. You can also add files to the configs/ and includes/ subdirectories; see File Structure.

Set the API Key

The server does not start without an API key. Store the key in a file that only root can read:

sudo mkdir -p /etc/recyclarr
echo "RECYCLARR_API_KEY=$(openssl rand -hex 32)" | sudo tee /etc/recyclarr/server.env >/dev/null
sudo chmod 600 /etc/recyclarr/server.env

systemd reads this file as root and passes the key to the server as an environment variable.

Create the Service

Create the unit file /etc/systemd/system/recyclarr.service with this content:

[Unit]
Description=Recyclarr server
Wants=network-online.target
After=network-online.target

[Service]
Type=notify
User=recyclarr
Group=recyclarr
Environment=RECYCLARR_CONFIG_DIR=/var/lib/recyclarr
EnvironmentFile=/etc/recyclarr/server.env
ExecStart=/usr/local/bin/recyclarr-server
Restart=on-failure

[Install]
WantedBy=multi-user.target

• Type=notify
  The server tells systemd when it is ready to accept requests. Until then, systemctl start waits, and if startup fails, the command reports the failure.
• RECYCLARR_CONFIG_DIR
  Sets the configuration directory. Always use an absolute path here.
• ExecStart
  Starts recyclarr-server directly. Do not use recyclarr serve or a wrapper script; systemd then cannot get the ready signal, and the start times out.
• Restart=on-failure
  Starts the server again when it exits with an error. A normal stop does not restart it.

Then enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now recyclarr

systemctl status recyclarr shows active (running) when the server is ready. If the configuration or API key is not valid, the service shows failed instead.

Logs

The server writes its log messages to the systemd journal:

journalctl -u recyclarr -f

Each message is a JSON line. For plain text, set server.logging.format to text.

It also writes log files to /var/lib/recyclarr/logs/server/.

Run CLI Commands

The CLI sends commands to the server over HTTP. To use the service, give the CLI the server address and the API key in ~/.config/recyclarr/cli.yml (the CLI settings file for your own user):

server:
  base_url: http://localhost:7982
  api_key: your-key-here

Use the key from /etc/recyclarr/server.env. Then run commands as usual:

recyclarr sync

Without cli.yml, each command starts its own temporary server and does not use the service. The server listens on port 7982 on the local machine only. To change this, see the server settings.

Configuration Changes

The server reads your YAML configuration and settings.yml once, when it starts. After you change them, restart the service:

sudo systemctl restart recyclarr

Upgrade

Linux cannot replace an executable while it runs, so stop the service first. Then download the new release with the manual installation command and start the service again:

sudo systemctl stop recyclarr
wget "$RECYCLARR_URL" -O - | sudo tar xJ --overwrite -C /usr/local/bin
sudo systemctl start recyclarr