{"id":46654819,"url":"https://github.com/hollanbm/renamarr","last_synced_at":"2026-04-26T07:02:20.003Z","repository":{"id":235958882,"uuid":"791617633","full_name":"hollanbm/renamarr","owner":"hollanbm","description":"automatically scans and renames files using the sonarr/radarr API","archived":false,"fork":false,"pushed_at":"2026-04-18T20:40:08.000Z","size":503,"stargazers_count":61,"open_issues_count":4,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-04-18T21:27:59.501Z","etag":null,"topics":["radarr","radarr-api","radarr-companion","sonarr","sonarr-api","sonarr-companion"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hollanbm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-04-25T03:38:13.000Z","updated_at":"2026-04-18T20:40:10.000Z","dependencies_parsed_at":"2024-05-10T03:24:01.508Z","dependency_job_id":"0b77c9e9-ba04-43a0-a849-087917319989","html_url":"https://github.com/hollanbm/renamarr","commit_stats":null,"previous_names":["hollanbm/sonarr-series-scanner"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/hollanbm/renamarr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hollanbm%2Frenamarr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hollanbm%2Frenamarr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hollanbm%2Frenamarr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hollanbm%2Frenamarr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hollanbm","download_url":"https://codeload.github.com/hollanbm/renamarr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hollanbm%2Frenamarr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32288653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T06:26:00.361Z","status":"ssl_error","status_checked_at":"2026-04-26T06:25:58.791Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["radarr","radarr-api","radarr-companion","sonarr","sonarr-api","sonarr-companion"],"created_at":"2026-03-08T07:31:51.683Z","updated_at":"2026-04-26T07:02:19.998Z","avatar_url":"https://github.com/hollanbm.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Renamarr\n\n[![codecov](https://codecov.io/gh/hollanbm/renamarr/graph/badge.svg?token=8MJ61PXR4V)](https://codecov.io/gh/hollanbm/renamarr)\n\n## Quick Start\n\n### docker\n\n1. Copy/Rename [config.yml.example](example/config.yml.example) to `config.yml`\n2. Update `config.yml` as needed.\n   - See [Configuration](#configuration) for further explanation\n3. Bring up app using provided [docker-compose.yml](example/docker-compose.yml)\n\n#### Troubleshooting\n\nImage 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.\n\n## How it works\n\n### Renamarr\n\nThis job uses the [Sonarr API](https://sonarr.tv/docs/api/)/[Radarr API](https://radarr.video/docs/api/) to do the following\n\n- Iterate over all items (Movies or Series)\n  - Checks if any items need to be renamed\n    - Radarr [get_api_v3_rename](https://radarr.video/docs/api/#/RenameMovie/get_api_v3_rename)\n    - Sonarr [get_api_v3_rename](https://sonarr.tv/docs/api/#/RenameEpisode/get_api_v3_rename)\n  - Triggers a rename on any item that need be renamed\n    - Series renames are batched up, for one rename call per series\n    - Movie renames are initiated per movie.\n      - Example, 1 movie, 2 files. There will be 2 rename API calls\n\n#### Analyze Files\n\nThis 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\n\n#### Rename Folders (Sonarr Only)\n\nThis config option will rename series folders, when they no longer match your configured MediaFormat\n\n- uses [/api/v3/series/{id}/folder](https://sonarr.tv/docs/api/#/SeriesFolder/get_api_v3_series__id__folder) endpoint to determine if the series folder requires an update\n- uses [/api/v3/series/editor](https://sonarr.tv/docs/api/#v3/tag/serieseditor/PUT/api/v3/series/editor) endpoint to update series rootFolderPath to it's current value\n  - moving the folder in place\n- Series are processed in bulk at the end of the run, **per root folder**\n\n### Series Scanner (Sonarr Only)\n\nThis job uses the [Sonarr API](https://sonarr.tv/docs/api/) to do the following\n\n- Iterate over continuing [series](https://sonarr.tv/docs/api/#/Series/get_api_v3_series)\n  - If a series has an episode airing within `config.sonarr[].series_scanner.hours_before_air`\n    - default value of 4, max value of 12\n  - OR\n  - An episode that has aired previously\n  - With a title of TBA (excluding specials)\n    - will trigger a series refresh, to hopefully pull new info from The TVDB\n\nThis should prevent too many API calls to the TVDB, refreshing individual series, hourly\n\n### Usage\n\nThe application runs immediately on startup, and then continue to schedule jobs every hour (+- 5 minutes) after the first execution.\n\nLogs are always written to stdout.\n\n### File Logging\n\nSet `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.\n\nWhen enabled, logs for that instance are written under `/logs` using one of these paths:\n\n- `sonarr/\u003cname\u003e.log`\n- `radarr/\u003cname\u003e.log`\n\n_Don't forget to mount /logs outside the container to persist log files_\n\n_To avoid permission issues when creating log files, set the user option in docker-compose to match the desired runtime UID/GID._\n\n#### Logging Configuration and Defaults\n\n| Environment Variable | Description                                               | Default  |\n| -------------------- | --------------------------------------------------------- | -------- |\n| `LOG_LEVEL`          | Log level passed to Loguru for stdout and file sinks.     | `INFO`   |\n| `LOG_ROTATION`       | Rotation schedule passed to Loguru for file log rotation. | `00:00`  |\n| `LOG_RETENTION`      | Retention period passed to Loguru for rotated log files.  | `7 days` |\n\n_For more details on `LOG_RETENTION` or `LOG_ROTATION` values, see the [official documentation](https://loguru.readthedocs.io/en/stable/overview.html#easier-file-logging-with-rotation-retention-compression)_\n\n### Configuration\n\n| Name                                       | Type    | Required | Default Value | Description                                                                                                                                      |\n| ------------------------------------------ | ------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `sonarr`                                   | Array   | Yes      | []            | One or more sonarr instances                                                                                                                     |\n| `sonarr[].name`                            | string  | Yes      | N/A           | user friendly instance name, used in log messages                                                                                                |\n| `sonarr[].url`                             | string  | Yes      | N/A           | url for sonarr instance                                                                                                                          |\n| `sonarr[].api_key`                         | string  | Yes      | N/A           | api_key for sonarr instance                                                                                                                      |\n| `sonarr[].series_scanner.enabled`          | boolean | No       | False         | enables/disables series_scanner functionality                                                                                                    |\n| `sonarr[].series_scanner.hourly_job`       | boolean | No       | False         | disables hourly job. App will exit after first execution                                                                                         |\n| `sonarr[].series_scanner.hours_before_air` | integer | No       | 4             | The number of hours before an episode has aired, to trigger a rescan when title is TBA                                                           |\n| `sonarr[].renamarr.enabled`                | boolean | No       | False         | enables/disables renamarr functionality                                                                                                          |\n| `sonarr[].renamarr.hourly_job`             | boolean | No       | False         | disables hourly job. App will exit after first execution                                                                                         |\n| `sonarr[].renamarr.analyze_files`          | boolean | No       | False         | This will initiate a rescan of the files in your library. This is helpful if you are transcoding files, and the audio/video codecs have changed. |\n| `sonarr[].renamarr.rename_folders`         | boolean | No       | False         | This will rename series folders when the current series folder no longer matches your MediaFormat                                                |\n| `sonarr[].renamarr.log_to_file`            | boolean | No       | False         | writes logs for this Sonarr instance to `/logs/sonarr/\u003cname\u003e.log` with daily rotation                                                            |\n| `radarr[].renamarr.enabled`                | boolean | No       | False         | enables/disables renamarr functionality                                                                                                          |\n| `radarr[].renamarr.hourly_job`             | boolean | No       | False         | disables hourly job. App will exit after first execution                                                                                         |\n| `radarr[].renamarr.analyze_files`          | boolean | No       | False         | This will initiate a rescan of the files in your library. This is helpful if you are transcoding files, and the audio/video codecs have changed. |\n| `radarr[].renamarr.log_to_file`            | boolean | No       | False         | writes logs for this Radarr instance to `/logs/radarr/\u003cname\u003e.log` with daily rotation                                                            |\n\n### Local Development\n\nSee [Local Development](docs/local-development.md) for local development requirements, environment details, and startup commands.\n\nDependency audits are run with `uv audit --frozen --preview-features audit`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhollanbm%2Frenamarr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhollanbm%2Frenamarr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhollanbm%2Frenamarr/lists"}