Renamarr

This is the default deployment mode. Enabled Renamarr jobs run immediately, repeat every hour unless configured otherwise, and the container remains running with restart: unless-stopped.

1. Copy/Rename config.yml.example to config.yml
2. Update config.yml as needed.
   • See Configuration for further explanation
3. Bring up app using provided docker-compose.yml

Each invocation runs every enabled job once and exits without restarting when no recurring jobs are configured.

1. Copy/Rename config.yml.example to config.yml
2. Update config.yml as needed
   • Set sonarr[].renamarr.schedule.enabled to false for every enabled Renamarr instance.
   • Set radarr[].renamarr.schedule.enabled to false for every enabled Renamarr instance.
3. Invoke the app from your scheduler using the provided docker-compose.yml

Image tags ending in -dev can be used for troubleshooting purposes, but are not intended for normal usage. Pre-release images are tagged with their specific release version and do not change or overwrite the latest or latest-dev tags.

This job uses the Sonarr API/Radarr API to do the following

Sonarr API access uses devopsarr/sonarr-py, and Radarr API access uses devopsarr/radarr-py. Existing Sonarr and Radarr configuration remains unchanged.

• Iterate over all items (Movies or Series)
  • Checks if any items need to be renamed
    • Radarr get_api_v3_rename
    • Sonarr get_api_v3_rename
  • Triggers a rename on any item that need be renamed
    • Series renames are batched up, for one rename call per series
    • Movie renames are discovered per movie, then initiated in one batch command with all movie IDs that need a rename

This config option is useful if you have audio/video codec information as part of your mediaformat, and you are transcoding files after import. This will initiate a rescan of the files in your library, so that the mediainfo will be updated. Then renamarr will come through and detect changes, and rename the files

This config option will rename series or movie folders when they no longer match your configured MediaFormat.

• uses /api/v3/series/{id}/folder endpoint to determine if the series folder requires an update
• uses /api/v3/series/editor endpoint to update series rootFolderPath to it's current value
  • moving the folder in place
• uses /api/v3/movie/{id}/folder endpoint to determine if the movie folder requires an update
• uses /api/v3/movie/editor endpoint to update movie rootFolderPath to it's current value
  • moving the folder in place
• sends a Sonarr RescanSeries command to rescan series after successful folder moves
• sends a Radarr RefreshMovie command to rescan movies after successful folder moves
• Series and movies are processed in bulk at the end of the run, per root folder

Analysis, file rename, and post-move rescan commands use the same polling settings. Renamarr checks each command immediately, then checks every command_polling.check_interval_seconds until it succeeds, reports a completed failure, encounters a status-check error, or reaches command_polling.timeout_seconds. The timeout applies separately to each asynchronous command; it is not an HTTP request or whole-scan timeout.

The application runs enabled jobs immediately on startup. Renamarr jobs repeat every hour by default. Set renamarr.schedule.enabled to false to run once, or configure the interval in days, hours, and minutes.

The process remains running while at least one recurring job is registered. It exits after the initial run when every enabled Renamarr job has schedule.enabled set to false.

Logs are always written to stdout.

Each successful run ends with file and folder rename totals in the following format:

Finished Renamarr successfully | file renames: [ success=0, failed=0, skipped=373 ] | folder renames: [ success=0, failed=0, skipped=373 ]

Failed runs report the same totals at ERROR level after their individual errors. At DEBUG level, each run also reports its item count and analysis outcomes.

Set sonarr[].renamarr.log_to_file or radarr[].renamarr.log_to_file to true to enable per-instance log files. If the target log path is not writable, renamarr logs a warning to stdout and continues running without logging to file.

When enabled, logs for that instance are written under LOG_DIR (/logs by default) using one of these paths:

• sonarr/<name>.log
• radarr/<name>.log

Don't forget to mount /logs outside the container to persist log files

To avoid permission issues when creating log files, set the user option in docker-compose to match the desired runtime UID/GID.

For more details on LOG_RETENTION or LOG_ROTATION values, see the official documentation

Schedule interval values must be non-negative integers, and the combined interval cannot exceed 30 days. When scheduling is enabled, the combined interval must be greater than zero. A zero interval is valid only when schedule.enabled is false.

When schedule.interval is omitted or empty, Renamarr uses the default interval of one hour.

Command-polling values must be positive integers. check_interval_seconds cannot exceed timeout_seconds. The section is optional; omitting command_polling, or the entire renamarr section, uses a two-minute timeout and a three-second check interval.

The container publishes application health through Docker's native health status. Renamarr refreshes an internal heartbeat while the scheduler is idle and from a background thread while a job is running. The health check is observational: Docker Compose's restart policy does not restart a running container solely because it becomes unhealthy. A logically stuck job can remain healthy while its heartbeat thread continues running.

The heartbeat is stored under /tmp. Containers invoked by an external scheduler may finish before Docker runs a health check. For these runs, use the container’s completion status and Renamarr logs rather than Docker health status.

The included Compose configurations run Renamarr with a read-only root filesystem. The heartbeat is written to /tmp, so that path is mounted as a writable tmpfs.

When file logging is enabled, /logs must also be mounted as a writable volume; otherwise, Renamarr warns and continues with stdout logging.

See Local Development for local development requirements, environment details, and startup commands.

The mise configuration installs the development toolchain and provides tasks for the common workflows:

mise install
mise run sync
mise run check
mise run audit
mise run docker-build