.plexcached array files - reducing move operations update

[StudioNirin]

Ok so the way I'm imagining that it would work -

1. User adds a file to watchlist or their onDeck.
2. Plexcache adds the file as 'needed on cache'
3. Plexcache looks for the file and finds it on the array ( /mnt/user0/whatever ) - I guess the best way to validate it's on the array is just by the user0 in the path as I think that's fixed for all unraid users.
4. I think it would need to copy the file to cache first, and -then- rename the file on the array. [^1] [^2]
5. File on array renamed to filename.mkv.plexcached (I know we discussed .archived but I just think using something that will be totally unique may be helpful, in case .archived is actually already used by something obscure.)
6. File gets watched.
7. Plexcache sees file is no longer needed, and I -think- it would need to rename the array file to it's normal name, and then delete the cached file. [^1]

[^1] - The reason why I say the files need to be renamed and removed in those orders, is so that there is always a file of that name on the /mnt/user file system that plex looks at. Otherwise if the move takes long enough, plex might remove the file from it's library temporarily before readding it when it finds it again. This can cause re-scans, or re-generating thumbnails etc, which wouldn't be ideal.

[^2] - The only thing to check for, is that I know unraid does -not- like having two files the same on both the array and the cache occupying the same place on the /mnt/user FUSE directory. I don't think it does much about it, but it gets confused about which one to prioritise. As it will only be happening for very short periods of time I -think- it'll be ok though.

Figured I'd write all this out here so there is a vague plan in place. Open to ideas / feedback / suggestions on it though!

@Brandon-Haney - Figured having a dedicated discussion page for this instead of doing it via issues and push request threads was a good idea haha.

[Brandon-Haney]

This looks great, I completely agree with the reasons to copy then rename. I will research more on unraid FUSE to ensure its not going to cause any issues but this is exactly where I was headed. Glad to see we are on the same page. I'm trying to finish my progress bar tonight then I will give this a proper try.

Teaser

[StudioNirin]

Ha, that looks great. Just a shame I generally run mine via userscripts so I dont see the live command line lol

[Brandon-Haney]

Ha, that looks great. Just a shame I generally run mine via userscripts so I dont see the live command line lol

Same here but while doing all this debugging I was doing a lot of copying and no indicator was annoying me.

[StudioNirin]

@Brandon-Haney Figured I'd move the discussion back to here as that PR is closed off now anyway.

I moved over your branch to my setup just to test it (I don't know if you were ready for it but I was curious) and so just wanted to give feedback on it so far:

1. I like the new additions to the setup script. And making it append the new options to an existing setup is a good touch. I'd have just make people delete the old settings.json and run the setup from scratch haha.
2. The 'retention policy' is fine, but for testing purposes I can see it being annoying, as I already commonly have to delete the watchlist_cache in order to get the script to quickly update things so I can check if changes have worked. Is there a quick way to disable the retention policy for testing purposes? I did consider just trying "0" but I didn't know if you'd accounted for that value.
3. Setting a drive-space limit is a great touch. I took a look through the code for that and it's set up nicely. It would be nice if it could have some handling in the future where, if it detects plexcache is using that much space, it prioritises removing watchlist items in favour of onDeck items or something. But that's for future complications, it's already a great addition.
4. I like how it does the automatic creation of .plexcached files on the first run of the script, though I'll have to check the code to see what metrics it uses to decide what items to create .plexcached files for. But it's running right now and seems to be working well! Github is still indexing your new branch so I cant easily search around to find connections so I'll do that later.
5. I also noticed that you had the same idea I did - adding in some kind of method of converting all the .plexcached files back to normal. I had thought about adding that in case a user decided they no longer wanted to use plexcache anymore, there would need to be a way to get them 'back to stock' without harming anything. But seems you're ahead of me! I can't see where/how it's triggered (indexing still going on) but it looks sensible so far.

That's all I have for now, cos it's doing the process of creating .plexcached files on my array so I can't get any further in testing until that's finished haha.

[Brandon-Haney]

• Yes you can set retention to 0 and it will immediately remove the files on next script run.
• Agreed, we should make a future enhancements list to document that.
• Yeah I did an initial migration based on the exclude files, other items I figured would be moved back by mover eventually. (I have exclude file used by my mover to keep those)
• I added that for my testing... I was trying not to make more work later.

[StudioNirin]

I have a list in discussions which is a kind of catch-all "to do list and proposed feature ideas" so I'll add it in there now.

For the "PlexcachedRestorer" function, I had originally considered it would be something similar to the setup.py script. Something with instructions that say "if you're quitting using plexcacheR, run this "Restore" script, and it will reset all files and return you back to stock unraid usage" or something. Having it be it's own separate script file and a kind of reset-all button. But I don't know if that's actually the best way to handle it, just how I imagined it at the time!

[StudioNirin]

What is the purpose of the new 'timestamps' file that is created? Mine seems to only contain -

{
"/mnt/hex-drive/media/tv/series/Rome (2005)/Season 2/Rome - S02E10 - De Patre Vostro About Your Father (Bluray-1080p).en.srt": {
"cached_at": "2025-12-03T04:57:57.246091",
"source": "ondeck"
}
}

Edit:
Also, I just checked after running the script again, and just-watched episodes weren't moved off the cache and onto the array. And while the current season I'm watching does seem to be on the cache drive, it's not listed in the exclude file at all.
Correction - I'm on S01E12 (out of a 12 episode season) but the only episode on the Exclude file is S02E10. All the rest aren't listed.

[Brandon-Haney]

Timestamps file: This tracks when each file was cached and its source (ondeck/watchlist). It's used for the retention period feature, files stay on cache for X hours (default 12h) after being removed from OnDeck/watchlist before moving back to array. This protects against accidental removal if you temporarily stop watching something. (Also allows times for other who might watch the same thing later that day, recent episodes)

Regarding the exclude file issue: That does sound like a bug. Can you share a log file from a recent run? That'll help me see what the script is detecting for Rome and why files aren't being added to the exclude list properly. (Might run with --verbose for extra detail)

[Brandon-Haney]

@StudioNirin
I found a bug I introduced, the token caching refactor in commit d529c4b broke OnDeck tracking for remote users. I added a check that skipped all remote users during token loading, which meant their OnDeck items were never fetched.

Fix: Implemented a hybrid token loading approach that:

1. Loads tokens from the settings file first (which already has all users including remote)
2. Falls back to Plex API for any new users not in settings

This restores remote user OnDeck tracking while keeping the token caching performance benefits. Commit c9ccb00 on the exclude branch has the fix.

[StudioNirin]

@Brandon-Haney Recent log file. It seems to show the correct episodes onDeck (current ep + the number to look ahead from that) but they aren't in my exclude file.

plexcache_log_20251203_0718.log

plexcache_mover_files_to_exclude.txt

I just checked the array and the missing files are also not on the array, but they are on cache, so the auto-.plexcached creation on first run of the script didn't copy those files. It did copy the s02e10 one though. So I don't know why. However that may explain why it doesn't work now, if the script relies on .plexcached files existing in order to work, so perhaps the issue was with the creation/upgrade to current version step.

[Brandon-Haney]

If you get a chance later I added handling for the radarr file update, I haven't tested it out yet but will try it tomorrow.

[StudioNirin]

2025-12-04 00:29:55,424 - INFO - Edited path: /mnt/user/media/movies/movies/It Chapter Two (2019)/It Chapter Two (2019) (Bluray-1080p h265).mkv
2025-12-04 00:29:55,425 - INFO - Found 137 files in exclude list
2025-12-04 00:29:55,438 - INFO - Found 0 files to move back to array
2025-12-04 00:29:55,439 - INFO - No files need to be moved back to array
2025-12-04 00:29:55,439 - INFO - Phase 9: Moving files
2025-12-04 00:29:57,996 - INFO - Adding file to array: /mnt/user/media/movies/movies/Wreck-It Ralph (2012)/Wreck-It Ralph (2012) (WEBDL-1080p x264).mkv
2025-12-04 00:29:58,241 - CRITICAL - Error moving media files to array: FileNotFoundError: [Errno 2] No such file or directory: '/mnt/user/media/movies/movies/Wreck-It Ralph (2012)/Wreck-It Ralph (2012) (WEBDL-1080p x264).mkv'

Seemed to make no difference.
Though looking now, wreck it ralph isn't on my exclude list, or in my watchlist. The only file that mentions it is the log, and only at the very end when it says it needs to be moved to the array. So I have no idea why it's even being processed.

plexcache_log_20251204_0032.log

I guess cos it happens to be in cache, but the script shouldn't be processing anything that's in cache unless its also onDeck or on a watchlist.

[Brandon-Haney]

Alright I had an extra few mins before we had to leave tonight, here is a test...

Before I had Radarr update the file to a new version...

root@Alpha:/mnt/user0/Movies# ls -la Hall\ Pass\ \(2011\)/
total 5072504
drwxrwxrwx 1 nobody users         95 Dec  3 18:23 ./
drwxrwxrwx 1 nobody users      57344 Dec  2 16:51 ../
-rw-rw-rw- 1 nobody users 5194161560 Jun 12 01:29 Hall\ Pass\ (2011)\ -\ [BLURAY-1080P][AC3\ 5.1][X264][8Bit]-OFT.mkv.plexcached

root@Alpha:/mnt/cache_downloads/Movies# ls -la Hall\ Pass\ \(2011\)/
total 4190960
drwxrwxrwx 1 nobody users        136 Dec  3 18:31 ./
drwxrwxrwx 1 nobody users       1812 Dec  3 18:23 ../
-rw-rw-rw- 1 nobody users 4291542575 Jun 10  2017 Hall\ Pass\ (2011)\ -\ [EXTENDED][BLURAY-1080P][AC3\ 5.1][X264][8Bit].mp4

After I had Radarr update, I marked the movie as watched.

2025-12-03 18:33:50,744 - INFO - --- Moving Files ---
2025-12-03 18:33:50,909 - INFO - Adding file to array: /mnt/user/Movies/Hall Pass (2011)/Hall Pass (2011) - [EXTENDED][BLURAY-1080P][AC3 5.1][X264][8Bit].mp4
2025-12-03 18:33:50,910 - INFO - Moving 4.00 GB to array
2025-12-03 18:33:50,910 - INFO - Moving media files to array...
2025-12-03 18:33:50,910 - INFO - Generated 1 move commands for array
[░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0% (0/1) - 0 B / 4.0 GB - Moving to array...
  Currently moving (1 active):
[██████████████████████████████] 100% (1/1) - 4.0 GB / 4.0 GB - Moved to array
2025-12-03 18:34:02,643 - INFO - Finished moving files with 0 errors.
2025-12-03 18:34:02,663 - INFO - Cache limit: 70% of 1863.0GB = 1304.1GB, current usage: 493.45GB
2025-12-03 18:34:02,663 - SUMMARY - Total size of media files moved to array: 4.00 GB
2025-12-03 18:34:02,665 - INFO - Cleaned up 2 empty folders
2025-12-03 18:34:02,666 - INFO - Cleaned up 1 stale timestamp entries
2025-12-03 18:34:02,666 - INFO -
2025-12-03 18:34:02,666 - INFO - Completed in 56 seconds
2025-12-03 18:34:02,666 - INFO - ===================

Outcome:

root@Alpha:/mnt/user0/Movies# ls -la Hall\ Pass\ \(2011\)/
total 4191040
drwxrwxrwx 1 nobody users         90 Dec  3 18:33 ./
drwxrwxrwx 1 nobody users      57344 Dec  2 16:51 ../
-rw-rw-rw- 1 root   root  4291542575 Jun 10  2017 Hall\ Pass\ (2011)\ -\ [EXTENDED][BLURAY-1080P][AC3\ 5.1][X264][8Bit].mp4

root@Alpha:/mnt/cache_downloads/Movies# ls -la Hall\ Pass\ \(2011\)/
ls: cannot access 'Hall Pass (2011)/': No such file or directory

Issue:

Exclude list was not updated to remove the old filename

🟡 In exclude list but NOT on cache (1):
   (Stale entries - files were moved/deleted)
   - Hall Pass (2011) - [BLURAY-1080P][AC3 5.1][X264][8Bit]-OFT.mkv

Will work on it more later

[StudioNirin]

my issue (I posted a reply same time you did so I dunno if you saw it) seems to be that it's getting stuck on wreck it ralph even though ralph isn't even a file plexcache should be looking at (it's not mentioned as being onDeck or in a watchlist, it's just on the cache drive.).

But I can't figure out in that case where it's getting the old mnt/ path from, when it doesn't -seem- to be saved anywhere in plexcache.

I did wonder if it had a .plexcached file, but cos it wasn't added or ever used by plexcache it doesn't have one.

HOWEVER - This made me realise an issue. The .plexcached files.
If radarr updates the known file (which would I assume be the .mkv) with a new version, then the .plexcached file won't be correct anymore. So we wouldn't want to revert to that file. So we would need to know if the array file no longer 100% matches the cached file, and update/remove that .plexcached version.

It would need to match -
filename fully
file type
size on disk

Not something I thought of before, but it's going to be a very common occurence for anyone who uses sonarr and radarr.

Edit:
I think the way to handle it would be:

1. File on cache has been detected as no longer needed, so plexcache is going to move it to array.
2. Check array file for a matching .plexcached file (name/type/size).
3. If it matches, rename array file and delete cached file.
4. If it doesn't match, delete array file and move cached file to array.

[StudioNirin]

Update: I can only assume it's because that link for wreck-it-ralph is in the 'watched' cache list, and it's still on cache (it was watched a long time ago). Except the file on cache is a different name because it's been updated.
but plexcache shouldn't be using the watched list in this way really.

Edit:
I could fix it by deleting that entry so wreck it ralph fixed itself, but at the moment I'm thinking I'll just leave it cos the script should be able to handle/avoid issues like that I guess. If I remove it then we'll have nothing left to test with aha.

[StudioNirin]

@Brandon-Haney moved the discussion here as I realised we were in the proposals thread haha.

plexcache_log_20251204_2115.log

Ok so I ran a test by adding two things to my watchlist, a movie (venom) and a tv series (9 out of 10 cats) but only the movie has been added to cache and picked up in the log. I checked and the new "watchlist tracker" and the exclude file and only venom appears in both.

Edit:
I'll also add that I like the way you have formatted the 'watchlist tracker', the bexem watchlist_cache was a pain to look at. I would assume that we could soon remove the watchlist_cache file entirely and just use the tracker file? (After a working release of v2.0 my next goal will be streamlining the script and codebase down as much as possible)

[StudioNirin]

plexcache_log_20251205_0055.log

[Brandon-Haney]

plexcache_log_20251205_0055.log

Log shows your Plex has this show as "Watched" so they were ignored,

  1328:2025-12-05 00:55:51,694 - DEBUG - Processing show 8 Out of 10 Cats with 232 episodes (limit: 6)
  1329:2025-12-05 00:55:51,694 - DEBUG -   8 Out of 10 Cats: 0 episodes to cache, 6 skipped (already watched)

[StudioNirin]

Ahh, probably true, though that was a long time ago. For some reason I thought the updated version you sent included the parts where we not longer have/use a 'watched files' list, I thought that's what I was testing haha

[Brandon-Haney]

I had not made that change yet because I had pushed a lot of changes already.

[StudioNirin]

I had not made that change yet because I had pushed a lot of changes already.

My mistake!
Yeh I've pretty much put my alterations on hold, because your next PR it going to change a bunch of the code already and if I try and add to it it's only going to complicate things.

Let me know if there's anything that needs to be tested or run through and I'll take a look

[scuppasteve]

Now that you all have helped me get this new version working for me. I am not sure if this is the right place to comment regarding this. But, i just wanted to ask a couple questions regarding this. While i know this may not be limited to Unraid, it definitely seems like that is at least one of main OS platforms. With that said, when looking at Mover Tuning. I am trying to figure out the best way to have PlexCache move the files and not be fighting Mover settings. Based on the Mover Tuning plugin, i think copying the files from the array really is the only answer i can figure. Especially if it creates the new files with new file dates. This would allow Mover Tuning to be configured to ignore new files for X days at least. Maybe i am overlooking something. I appreciate the work you all are putting in for this.

[StudioNirin]

@scuppasteve
Hi, yeh this is meant to be the ideal place to discuss updates and features, though I notice github doesn't seem to actually flag discussions when they have 'new replies' in them, while one the Issues page threads with new replies get a highlight so it's easier to see what needs to be checked. So I may end up moving these discussions over to the issues page. Not sure yet.

But anyway haha onto your question - you should be using the Mover Tuner option for using an 'exclusion text file'. Plexcache generates a text file which holds all the cached files as a list, and so Mover will ignore all those files until plexcache is finished with them.

This file is currently called plexcache_mover_files_to_exclude.txt but after V2.0 (which is coming very soon) the file you want will be called "unraid_mover_exclusions.txt".

[scuppasteve]

@scuppasteve Hi, yeh this is meant to be the ideal place to discuss updates and features, though I notice github doesn't seem to actually flag discussions when they have 'new replies' in them, while one the Issues page threads with new replies get a highlight so it's easier to see what needs to be checked. So I may end up moving these discussions over to the issues page. Not sure yet.

But anyway haha onto your question - you should be using the Mover Tuner option for using an 'exclusion text file'. Plexcache generates a text file which holds all the cached files as a list, and so Mover will ignore all those files until plexcache is finished with them.

This file is currently called plexcache_mover_files_to_exclude.txt but after V2.0 (which is coming very soon) the file you want will be called "unraid_mover_exclusions.txt".

@StudioNirin
Thanks for the response, that is super helpful and i didn't know that. Thanks for all the help so far and i appreciate the work!