How to use - unraid

[matterbyte]

interested in using plexcache-d, but curious about what's the correct way to use it as it's not working for me currently the way I initially set it up (Docker install from CA store)

Do I need to set shares for media to have cache drive as secondary storage so that plex can find the files there when plexcache-d moves them there? or would i set up a separate share on the cache drive for plexcache-d to move the media files to?

using linuxserver/plex image for reference.

[Brandon-Haney]

Hey @matterbyte — good questions, and the short answer is: you don't need either of those approaches. Both assume PlexCache-D moves media to a new location that Plex then has to be told about. It doesn't work that way, and that's the key thing to get straight.

How it actually works

Unraid's user shares (/mnt/user/...) are a FUSE overlay that merges your cache drive and your array disks into one view. A file at /mnt/user/Media/Movies/Foo.mkv resolves to the same path whether the file physically lives on the array or on the cache pool. PlexCache-D just moves the physical copy between the array and cache — the /mnt/user/... path Plex sees never changes. Plex doesn't know (or care) that the file got faster.

So:

• ❌ You do not need to add the cache as "secondary storage" in Plex.
• ❌ You do not need a separate share for PlexCache to move files into.
• ✅ Plex and PlexCache-D both just point at your existing media share. PlexCache shuffles the bytes underneath.

What you actually need to check

1. The media share must allow cache use. In Unraid → Shares → your media share, set Use cache pool (or Primary storage = cache, secondary = array on newer Unraid) so files are allowed to live on the cache. PlexCache handles the actual movement; this just permits it.

2. Container mounts (CA template defaults are correct — don't trim them). The PlexCache-D container needs /mnt/user, /mnt/user0, and /mnt/cache mounted. These look redundant but each is required: /mnt/user is the merged view, /mnt/user0 is the array-direct path PlexCache uses for safe existence checks, and /mnt/cache is the cache pool. The CA template ships them for a reason.

3. Path mappings must match between Plex and PlexCache. This is the most common cause of "it's not working." Your linuxserver/plex container reports file paths the way it sees them (e.g. /data/Movies/... or /media/..., depending on your volume mapping), but the real host path is /mnt/user/Media/Movies/.... PlexCache's setup wizard / Libraries tab maps one to the other. If that mapping is off, PlexCache can't find the files to move. Run the setup wizard (or check the Libraries tab in the web UI) and confirm each library's Plex path → real path mapping is correct for your linuxserver/plex volume layout.

4. Let PlexCache manage the Unraid Mover, not fight it. PlexCache maintains plexcache_cached_files.txt, an exclude list so the Unraid Mover doesn't drag your cached files back to the array on its schedule. Make sure that's wired up (the setup covers it).

To help debug "not working"

What specifically is happening? Screenshots and logs will make this much faster to pin down — could you share:

• The log from a dry run: run with --dry-run --verbose (or check the Logs tab in the web UI). Dry-run shows what it would move without touching anything — a screenshot or paste of that output is the single most useful thing.
• A screenshot of your PlexCache Libraries/path-mapping settings (the web UI Libraries tab, or what the setup wizard detected).
• A screenshot of your linuxserver/plex container's volume mappings (host path → container path) from the Unraid Docker tab.
• A screenshot of your media share's cache settings (Unraid → Shares → your share).

Nine times out of ten the issue is a path-mapping mismatch in 3. Post those and we'll get it sorted.

[matterbyte]

@Brandon-Haney thanks for the explanation, I had mistakenly assumed PlexCache-D worked in some special way. With this understanding, I updated the shares to include cache and pathing in docker to match and it is working as intended now.