Path Mapping

When Sonarr says /data/series/Frieren/Season 01/E01.mkv and Sublarr’s container only has /media/series/Frieren/Season 01/E01.mkv mounted, Sublarr needs to translate the prefix. Path Mapping is that translation table — one or more prefix-replacement rules applied to every path Sonarr or Radarr hands over.

When you need it

Setup	Need a mapping?
Sonarr, Radarr, and Sublarr in the same docker-compose mounting the same volume at the same path	No — paths already match.
Sonarr in one container at /data/series, Sublarr at /media/series	Yes — replace /data/series → /media/series.
Sonarr on a different host (NFS-mounted into Sublarr)	Yes — replace the remote path with the local mount point.
Standalone mode (no Sonarr/Radarr)	No — Sublarr reads paths directly from disk.

The mapping table

Each row is one prefix-replacement rule. Of the rules whose remote path contains the file, the one with the longest remote path is applied, whatever order the rows are in.

Field	Effect
Remote Path	The folder Sonarr/Radarr uses. A rule matches that folder and everything inside it.
Local Path	What to replace it with. Must exist inside Sublarr’s container.

Add Mapping adds a row, the bin icon removes one. The rules apply to every connected *arr instance.

Note

A rule matches whole folders: a rule for /data/series does not touch /data/series-4k/…. A trailing slash on either side is fine, and a specific rule (/data/anime) wins over a general one (/data) in any order.

Where the values come from

Side	How to find it
Source prefix	Open Sonarr/Radarr → Series → any episode → “File path”. Take the path up to but not including the series folder.
Target prefix	Inside Sublarr’s container, run ls on the same series and copy the path up to the same point.

The two prefixes typically share a common suffix — that’s the part you keep. The differing leading parts are what the rule rewrites.

Examples

Sonarr path	Mapping	Sublarr path
/data/series/Frieren/...	/data/series → /media/series	/media/series/Frieren/...
Z:\Anime\Frieren\E01.mkv	Z:\Anime → /media/anime	/media/anime/Frieren/E01.mkv
\\NAS\series\Frieren\...	\\NAS\series → /mnt/nas/series	/mnt/nas/series/Frieren/...

Tip

Sublarr handles Windows-style backslashes and UNC paths on the source side, even though it itself runs in a POSIX container. Define the rule in whatever shape Sonarr/Radarr emits — Sublarr normalises during application.

Validating a mapping

Test Path Mapping at the bottom of the section takes a real Sonarr/Radarr path and shows what Sublarr translates it to, plus whether that file exists:

Result	Meaning
✓ File exists	Sublarr can read the file.
✗ File not found	Either no rule matched (the path is shown unchanged), or the mapping is correct in shape but the local path isn’t actually mounted. Check the rule and your Docker volumes.

Common pitfalls

Symptom	Likely cause	Fix
Sublarr “can’t find” Sonarr episodes	Mapping prefix doesn’t match Sonarr’s actual paths	Use Test with a real Sonarr path to confirm.
Some series work, others don’t	Sonarr has multiple root folders; only one is mapped	Add a rule per root folder.
Mapping works for movies but not series	Sonarr and Radarr use different roots; only one is mapped	Add a rule for each root.
A path is rewritten by the wrong rule	Overlapping rules; the first match in the list wins	Move the more specific rule above the general one, or remove the redundant one.

Media servers have their own mapping

This page maps Sonarr/Radarr’s paths to Sublarr’s. When Plex, Jellyfin, Emby, Kodi or Shoko see the files under yet another path, that is set per server in its Path Mapping field under Settings → Connections → Media servers — from:to pairs from Sublarr’s path to the server’s, separated by ;, where the longest match wins and only whole folders match.

Where this is configured

Path Mapping lives at Settings → Connections → Path mapping. The same editor appears in step 4 of the onboarding wizard so you can set up the most common mapping while connecting your *arr instances.