Skip to content

Installing PlexCache‐R

Jump to bottom
StudioNirin edited this page Feb 16, 2026 · 8 revisions

Work in Progress, may not be up to date yet with the PlexCache-D v3 release

These instructions should still work with PlexCache v2.1.2 LTS branch, which was the last version of PlexCache-R.

Step 1: Getting the Files

Put the files from this Repo into a known folder on your Unraid server. I use the following:

/mnt/user/appdata/plexcache/plexcache_app.py

I'll keep using this in my examples, but make sure to use your own path.

Step 2: Configure the script:

PlexCache‐R UserScripts Setup

Generating your plexcache_settings.json file

This guide provides step-by-step instructions on setting up Plex Cache using Python. The instructions below are applicable to Unraid.

I have used /mnt/user/appdata/plexcache/ as my folder for PlexCache-R, but you can install it wherever you prefer. Just make sure to

Checking Python Installation To begin, let's check whether Python is already installed on your system. Follow the steps below:

  • Open the Terminal.
  • Type the following command and hit enter: python3 --version

If you see a version number displayed, then Python is already installed on your system, and you can skip to the next section. If not, proceed to the next step.

Installing Python

If Python is not installed, you need to download and install it.

Fortunately on Unraid it's currently quite easy. Just go to community apps and search for Python. Install.

Installing Requirements

  1. Open the Terminal.
  2. Type the following command and hit enter: cd ../mnt/user/appdata/plexcache/
  3. Type the following command and hit enter: pip3 install -r requirements.txt

Running the PlexCache-R Setup Script

Once you have installed Python and the required modules, you can run the setup script. Follow the steps below:

  1. If you're not already in your PlexCache folder, type the following command and hit enter: cd ../mnt/user/appdata/plexcache/
  2. Type the following command and hit enter: python3 plexcache_setup.py
  3. Follow the instructions. They should (hopefully) explain themselves. But I may add a descriptive list here at some point, especially if it's requested.

For guidance on each of the setup questions/options, look at the Setup File Guide

Running PlexCache-R on Unraid using UserScripts

Step 1: Install Required Dependencies

Python dependencies don't persist between Unraid server reboots since only the community Python app remains installed. To address this, modifications are made to the script triggering PlexCache-R.

Step 2: The User Scripts Plugin

Users can implement the User Scripts plugin to execute the script. Install the User Scripts plugin from the Unraid forums/Community Applications.

Provided Script:

#!/bin/bash
cd /mnt/user/appdata/plexcache
pip3 install -r requirements.txt
python3 /mnt/user/appdata/plexcache/plexcache_app.py

The script moves to the plexcache folder, installs dependencies (or confirms existing ones), and triggers the main PlexCache-R application.

Scheduling: You can set the schedule via dropdown options including "At startup," "Hourly," "Daily," or "Weekly." We recommend using Cron scheduling, with midnight daily as an example: 0 0 * * *

Important: Please ensure to replace the placeholder paths and commands with those that suit your specific setup.

Mover Exclusions Configuration

PlexCache uses a two-file system to manage Unraid mover exclusions:

File Purpose
plexcache_mover_files_to_exclude.txt Internal tracking - PlexCache maintains this list of currently cached files. Do not point Mover Tuning to this file.
unraid_mover_exclusions.txt For CA Mover Tuning - Point Mover Tuning to this file. Contains a marker line allowing you to add your own exclusions above it.

How It Works

  1. PlexCache tracks cached files in plexcache_mover_files_to_exclude.txt
  2. At the end of each run, entries are copied to unraid_mover_exclusions.txt below the marker line: 
    ### Plexcache exclusions below this line
/mnt/cache/media/Movies/MovieName (2024)/MovieName.mkv
/mnt/cache/media/TV/ShowName/Season 01/Episode.mkv
  3. You can add your own exclusions above the marker line - PlexCache won't touch them

CA Mover Tuning Setup

  1. Install the CA Mover Tuning plugin from Community Applications
  2. Go to Settings → Mover Tuning
  3. Set "Ignore files and folders listed inside of a text file" to: 
    /mnt/user/appdata/plexcache/unraid_mover_exclusions.txt
    (adjust path to match your PlexCache installation location)

Important Notes

  • Run PlexCache at least once before configuring Mover Tuning - the unraid_mover_exclusions.txt file is generated at the end of the first run
  • If you only see plexcache_mover_files_to_exclude.txt, run PlexCache and check again for unraid_mover_exclusions.txt

Step 3: Run PlexCache-R:

There are other methods to run the PlexCache-R script, but I've only tested and use the UserScripts one, so that's all I'll list here for now. UserScripts Setup. Click the link for full instructions and guidance.

Command Line Options

Flag Description
--dry-run Simulate run without moving files (useful for testing). Alias: --debug
--verbose Show detailed DEBUG level logging. Alias: -v
--restore-plexcached Emergency restore: scan for all .plexcached files and restore them to original names
--quiet Only send notifications on errors (suppresses summary notification). Alias: --notify-errors-only

Examples:

# Normal run
python3 plexcache_app.py

# Test run without moving files
python3 plexcache_app.py --dry-run

# Verbose output for troubleshooting
python3 plexcache_app.py --verbose

# Dry-run with verbose logging to see exactly what would happen
python3 plexcache_app.py --dry-run --verbose

# Restore all .plexcached backup files
python3 plexcache_app.py --restore-plexcached

# Run silently (only notify on errors) - ideal for scheduled cron jobs
python3 plexcache_app.py --quiet

# Combine flags as needed
python3 plexcache_app.py --dry-run --quiet

Migration from Original

The refactored version maintained full compatibility with the original. HOWEVER - This Redux version DOES NOT maintain full compatibility. I did make some vague efforts at the start, but there were so many things that didn't work properly that it just wasn't feasible. So while the files used are the same, you -will- need to delete your plexcache_settings.json and run a new setup to create a new one.

  1. Different Configuration: Uses the same plexcache_settings.json file, but the fields have changed
  2. Added Functionality: All original features still exist, but now also work (where possible) for remote users, not just local.
  3. Same Output: Logging and notifications work in a similar way, though they are now much improved.
  4. Same Performance: No performance degradation. Hopefully. Don't quote me on this.

Clone this wiki locally