Migrating Recyclarr to a new server is usually straightforward when you preserve the configuration files and move them to the correct location on the new system. Recyclarr is primarily configuration-driven, so the most important part of the migration is making sure your existing YAML configuration, secrets, and related settings are transferred correctly.
A typical migration involves stopping Recyclarr on the old server, backing up its configuration, installing the same or a compatible Recyclarr version on the new server, copying the configuration files, updating paths or environment-specific settings, and then testing the configuration before allowing scheduled synchronization to run. If Recyclarr is connected to Sonarr or Radarr, you should also verify that the new server can reach those applications and that the configured API credentials still work.
The exact commands depend on whether you run Recyclarr directly, through Docker, or as part of another self-hosted setup. The underlying migration process remains similar: preserve the configuration, recreate the runtime environment, validate connectivity, and perform a controlled sync.
What Should You Back Up Before Migrating Recyclarr?
Before moving Recyclarr, identify every file and setting that is required by your current installation. Your Recyclarr configuration files are the most important part because they contain the settings that define how your Sonarr and Radarr configurations are synchronized.
Depending on your setup, you may also need to preserve environment variables, Docker volume mappings, custom scripts, and any external files referenced by your configuration.
A useful backup should include:
- Recyclarr YAML configuration files
- Custom configuration files
- Environment variables used by Recyclarr
- Docker Compose files, if applicable
- Bind-mounted directories
- Custom scripts or supporting files
- Any configuration referenced through relative or absolute paths
Do not assume that copying the Recyclarr executable or container alone will reproduce your previous setup. The configuration and runtime settings are what make the installation behave as expected.
Step 1: Check Your Current Recyclarr Setup
Before shutting down the old server, document how Recyclarr is currently installed and launched.
For example, determine whether you are using:
- Docker
- Docker Compose
- A native installation
- A system service
- A scheduled task
- Another container-management platform
Also check where your Recyclarr configuration directory is located.
If you use Docker, inspect your container configuration and volume mappings. The host directory mapped into the Recyclarr container is particularly important because that is where your persistent configuration normally resides.
You should also record the connections to your Sonarr and Radarr instances. Note their URLs, API credentials, and any network-specific settings that may need to change after migration.
Step 2: Stop Recyclarr on the Old Server
Stop Recyclarr before copying its configuration to prevent files from changing while the backup is being created.
If you are using Docker Compose, the exact command depends on your Compose project, but the process generally involves stopping the Recyclarr service.
If Recyclarr is running as a system service, stop that service using the service manager configured on your operating system.
Stopping the application is especially useful when Recyclarr is scheduled to run automatically. You do not want a synchronization operation to start while you are creating the migration backup.
Step 3: Back Up the Recyclarr Configuration
Create a complete copy of the Recyclarr configuration directory.
For a Docker installation, look at the volume mapping in your Compose configuration. For example, a mapping may connect a host directory to the configuration directory inside the container.
Back up the host-side directory rather than copying files from inside a temporary container whenever possible.
Keep the backup intact until you have successfully tested Recyclarr on the new server.
A simple backup structure might look like this:
recyclarr-backup/
├── recyclarr.yml
├── sonarr.yml
├── radarr.yml
└── other-config-files/
Your actual structure may be different depending on your configuration.
Step 4: Review API URLs and Credentials
A server migration can change network addresses, hostnames, ports, or authentication details.
Before starting Recyclarr on the new server, review the Sonarr and Radarr connection settings in your configuration.
For example, your old configuration might point to:
http://192.168.1.20:8989
If Sonarr has moved to another server or address, Recyclarr must be able to reach the new endpoint.
The same applies to Radarr.
Do not change working settings unnecessarily. If Sonarr and Radarr remain at the same addresses and their API credentials are still valid, there may be no reason to modify those values.
Step 5: Install Recyclarr on the New Server
Install Recyclarr using the same deployment method you used previously, or recreate your existing containerized setup.
If you use Docker Compose, moving the Compose file along with the configuration makes the process more reproducible. Review the image version, volume mappings, environment variables, and restart policy before starting the new container.
If you are changing Recyclarr versions during the migration, check the release documentation for any configuration changes that could affect your existing YAML files.
Keeping the same version during the initial migration can make troubleshooting easier. Once the new server is working correctly, you can handle an upgrade separately.
Step 6: Copy the Configuration to the New Server
Transfer the backed-up configuration directory to the new server.
For Docker, make sure the directory is mapped to the location expected by the Recyclarr container.
One of the most common migration mistakes is copying the files successfully but mounting the wrong directory.
For example, you may have:
volumes:
- ./recyclarr:/config
In this example, Recyclarr expects the configuration to be available through the /config path inside the container.
The important thing is not the exact path shown above but the relationship between the host directory and the path expected by Recyclarr.
Step 7: Check File Permissions
File permissions can cause problems when moving a configuration directory between Linux servers.
The user running Recyclarr must be able to read the configuration files and, where necessary, write to the appropriate directories.
After transferring the files, inspect their ownership and permissions.
This is particularly important with Docker because the container may run under a specific user or group ID. A directory that was readable on the old server may not automatically have the correct ownership on the new server.
If Recyclarr starts but cannot read its configuration, permissions are one of the first things worth checking.
Step 8: Update Environment-Specific Settings
Not every setting should be copied unchanged.
Review configuration values that depend on the old server’s environment.
These can include:
- Sonarr URLs
- Radarr URLs
- API keys
- File paths
- Docker volume paths
- Environment variables
- Network hostnames
- Proxy settings
- Custom script locations
If your media applications are still running on the original server, make sure the new Recyclarr server can access them over the network.
For example, a configuration using localhost deserves particular attention. When Recyclarr moves to another machine, localhost refers to the new Recyclarr server, not the old server and not necessarily the machine running Sonarr or Radarr.
Step 9: Start Recyclarr Without Immediately Relying on Scheduled Runs
Once the configuration has been copied, start Recyclarr on the new server.
Before relying on its normal schedule, inspect the startup output and logs.
Look for problems involving:
- Configuration parsing
- Missing files
- Invalid YAML
- API authentication
- Network connectivity
- Sonarr availability
- Radarr availability
- File permissions
- Invalid custom format references
Starting with a controlled test makes it easier to identify whether the migration itself introduced a problem.
Step 10: Test the Configuration
Run a controlled Recyclarr configuration test before applying changes.
This is an important step because a successful application startup does not necessarily mean that every configuration is valid.
Check that Recyclarr can:
- Load the configuration.
- Connect to Sonarr.
- Connect to Radarr.
- Resolve the configured settings.
- Process custom formats and quality profiles correctly.
- Complete the intended synchronization without unexpected errors.
If the configuration uses multiple Sonarr or Radarr instances, test each one rather than assuming that one successful connection proves the entire migration works.
Step 11: Perform a Controlled Sync
After the configuration passes testing, perform a normal synchronization.
Watch the logs while the operation runs.
The goal is to confirm that the new server behaves like the old one and that Recyclarr is communicating with the correct Sonarr and Radarr instances.
Pay attention to unexpected changes. If the migration also involved changing configuration files, application versions, or API endpoints, separate those changes from the server move whenever possible.
A migration is easier to troubleshoot when the configuration remains unchanged.
Step 12: Verify Sonarr and Radarr After the Sync
After synchronization completes, check Sonarr and Radarr directly.
Confirm that the expected:
- Quality profiles
- Custom formats
- Custom format scores
- Quality settings
- Naming-related settings
- Other Recyclarr-managed configuration
are present as expected.
Do not assume that a successful Recyclarr log means every downstream setting is correct. The applications themselves are the final place to verify the result.
Migrating Recyclarr with Docker
Docker can make Recyclarr migration relatively simple because the application environment can be recreated from the container definition.
A typical migration consists of moving:
docker-compose.yml
configuration directory
environment variables
custom mounted files
Then recreate the container on the new server.
The most important Docker migration detail is the volume mapping. If your configuration directory is not mounted correctly, the new container may start with an empty or different configuration.
Before deleting the old installation, compare the old and new volume mappings.
Also check whether your Compose file references relative paths. Relative paths are resolved based on the location from which the Compose project is managed, so moving the project to a different directory can change what those paths point to.
What If Sonarr and Radarr Are Also Moving?
If Recyclarr, Sonarr, and Radarr are all being moved to a new server, perform the migration in a controlled sequence.
First, migrate the media applications and confirm that Sonarr and Radarr are functioning correctly. Then update Recyclarr’s connection settings to point to their new locations.
For example:
Old:
Recyclarr → Sonarr (old server)
Recyclarr → Radarr (old server)
New:
Recyclarr → Sonarr (new server)
Recyclarr → Radarr (new server)
Verify API connectivity before running a full synchronization.
If only Recyclarr moves and Sonarr/Radarr remain on the old server, the main requirement is network connectivity between the new Recyclarr server and the existing applications.
What If You Are Moving from Docker to a Native Installation?
The configuration itself can generally be migrated independently of the deployment method.
The important part is to place the configuration where the new Recyclarr installation expects it and recreate any environment variables or external file references.
Do not copy Docker-specific paths blindly into a native installation.
For example, /config may represent a container path rather than a physical directory on the host. Your native installation needs the corresponding host filesystem location instead.
What If the New Server Uses a Different Operating System?
Moving between Linux distributions, Windows, or other supported environments can introduce path and permission differences.
Review every path in your configuration that depends on the operating system.
For example:
Linux:
/config/recyclarr.yml
Windows:
C:\recyclarr\recyclarr.yml
The configuration content may remain largely unchanged, but filesystem paths and service-management procedures can differ.
Also check line endings, file permissions, executable settings, and environment-variable syntax where relevant.
Should You Change the Recyclarr Configuration During Migration?
It is generally easier to migrate first and modify the configuration afterward.
Changing multiple things at the same time makes troubleshooting much harder.
For example, avoid combining all of these changes into one migration:
- New server
- New Recyclarr version
- New Sonarr server
- New Radarr server
- New configuration structure
- New Docker setup
Instead, reproduce the existing working environment as closely as possible, verify it, and then make individual changes.
This gives you a clear baseline if something stops working.
Common Recyclarr Migration Problems
Recyclarr Starts With No Configuration
This usually indicates that the configuration directory was not copied correctly or the Docker volume mapping points to the wrong location.
Check the mounted configuration path first.
Recyclarr Cannot Connect to Sonarr or Radarr
Check the configured URL, port, API key, firewall rules, and network accessibility.
If the configuration uses localhost, remember that its meaning changes when Recyclarr moves to another machine.
Configuration Files Cannot Be Read
Check file ownership and permissions.
This is especially common when copying Linux configuration directories between servers or when a Docker container runs under a different UID or GID.
The Configuration Works but Scheduled Runs Fail
Check the new server’s scheduler, container restart policy, system service, or automation settings.
A successful manual test does not guarantee that the scheduled execution has been recreated correctly.
Paths No Longer Work
Look for hard-coded paths pointing to directories that existed only on the old server.
This can happen with custom files, scripts, volume mounts, or other externally referenced resources.
How Can I Confirm the Migration Is Complete?
A Recyclarr migration can be considered operationally complete when the new server can load the configuration, communicate with the intended Sonarr and Radarr instances, complete a test or synchronization successfully, and continue operating through its normal schedule.
A practical verification checklist is:
- Recyclarr is installed on the new server.
- The correct configuration files were copied.
- Docker volume mappings are correct, if applicable.
- File permissions are correct.
- Sonarr connectivity works.
- Radarr connectivity works.
- API credentials are valid.
- Environment-specific paths were updated.
- Configuration validation succeeds.
- A controlled synchronization completes.
- Sonarr and Radarr show the expected settings.
- Scheduled execution works.
- The old Recyclarr instance is stopped to prevent duplicate synchronization.
Once these checks pass, you can safely retire the old Recyclarr installation.
Conclusion
Migrating Recyclarr to a new server mainly involves preserving the configuration and recreating the environment that Recyclarr needs to operate. Back up the configuration first, install Recyclarr on the new server, restore the files, verify paths and permissions, check Sonarr and Radarr connectivity, and test the configuration before enabling normal scheduled synchronization.
If Sonarr and Radarr remain on the old server, focus on network access and API connectivity. If those applications are moving as well, update their endpoints after confirming the new installations work independently. Keeping the migration separate from configuration changes or version upgrades also makes troubleshooting considerably easier.
With the configuration backed up and the new environment verified, the actual Recyclarr migration should be a controlled transfer rather than a complete reconfiguration.