Your Plex directories are growing out of control. You use overlays from Plex Meta Manager (PMM) or upload lots of custom art from Title Card Maker (TCM) that you no longer want to use or need to eliminate. You don't want to perform the plex dance if you can avoid it. This script can free up gigs of space....
As well as being able to clean the PhotoTranscoder Directory and running the Plex operations Empty Trash, Clean Bundles, and Optimize DB.
Special Thanks to bullmoose20 for the original Plex Bloat Fix (PBF) Script this is based on.
This image shows which photos would be removed. Red is removed, Green is kept because it is the actively selected poster. The other two come standard from Plex when the posters are retrieved so the script will not touch those either:
Generally, Plex Image Cleanup can be installed in one of two ways:
- Running on a system as a Python script [we will refer to this as a "local" install]
- Running as a Docker container
GENERALLY SPEAKING, running as a Docker container is simpler, as you won't have to be concerned about installing Python, or support libraries, or any possible system conflicts generated by those actions.
For this reason, it's generally recommended that you install via Docker rather than directly on the host.
If you have some specific reason to avoid Docker, or you prefer running it as a Python script for some particular reason, then this general recommendation is not aimed at you. It's aimed at someone who doesn't have an existing compelling reason to choose one over the other.
There are no detailed walkthroughs specifically for Plex Image Cleanup but the process is extremely similar to how you would do it with Plex Meta Manager.
Plex Image Cleanup requires Python 3.11 or later. Later versions may function but are untested.
These are high-level steps which assume the user has knowledge of python and pip, and the general ability to troubleshoot issues.
- Clone or download and unzip the repo.
git clone https://github.com/meisnate12/Plex-Image-Cleanup
- Install dependencies:
pip install -r requirements.txt
- If the above command fails, run the following command:
pip install -r requirements.txt --ignore-installed
At this point Plex-Image-Cleanup has been installed, and you can verify installation by running:
python plex_image_cleanup.py
docker run -v <PATH_TO_CONFIG>:/config:rw -v <PATH_TO_PLEX>:/plex:rw meisnate12/plex-image-cleanup
-
The
-v <PATH_TO_CONFIG>:/config:rw
and-v <PATH_TO_PLEX>:/plex:rw
flags mount the location you choose as a persistent volumes to store your files and give access to plex.-
Change
<PATH_TO_CONFIG>
to a directory where your .env and other files are. -
Change
<PATH_TO_PLEX>
to the directory where your Plex Directory is (It contains directories: Cache, Metadata, Plug-in Support). -
If your directory has spaces (such as "My Documents"), place quotation marks around your directory pathing as shown here:
-v "<PATH_TO_CONFIG>:/config:rw"
-
Example Docker Run command:
These docs are assuming you have a basic understanding of Docker concepts. One place to get familiar with Docker would be the official tutorial.
docker run -v "X:\Media\Plex Image Cleanup\config:/config:rw" -v "X:\Plex Media Server:/plex:rw" meisnate12/plex-image-cleanup
Example Docker Compose file:
version: "2.1"
services:
plex-image-cleanup:
image: meisnate12/plex-image-cleanup
container_name: plex-image-cleanup
environment:
- TZ=TIMEZONE #optional
volumes:
- /path/to/config:/config
- /path/to/plex:/plex
restart: unless-stopped
A Dockerfile
is included within the GitHub repository for those who require it, although this is only suggested for those with knowledge of dockerfiles. The official Plex Image Cleanup build is available on the Dockerhub Website.
When running Plex Image Cleanup, make sure that you are not running any tools which may touch posters, backgrounds or title card images - namely Plex Meta Manager or TitleCardMaker.
It is recommended to schedule Plex Image Cleanup after the above tools or Plex's Scheduled Tasks.
An example schedule would be:
-
00:00-02:00 - TitleCardMaker
-
02:00-05:00 - Plex Scheduled Tasks
-
05:00-07:00 - Plex Meta Manager
-
07:00-09:00 - Plex Image Cleanup
-
Ensure you have proper permissions to delete/rename or the script will fail
-
For performance purposes, it's recommended to run locally so that accessing the files is not done over a network share
Plex Image Cleanup has multiple Global Options to change how it runs these are set in 3 different ways listed in priority order:
-
Setting the Environment Variable.
-
Adding the Environment Variables to
config/.env
example.env
is included as an example but is not read by the script it will only read a file specifically called.env
.
-
Use the Shell Command when launching.
PLEX_URL=http://192.168.1.12:32400
PLEX_TOKEN=123456789
PLEX_PATH=C:\Plex Media Server
MODE=report
SCHEDULE=
DISCORD=https://discord.com/api/webhooks/###################/####################################################################
TIMEOUT=600
SLEEP=60
PHOTO_TRANSCODER=False
EMPTY_TRASH=False
CLEAN_BUNDLES=False
OPTIMIZE_DB=False
TRACE=False
LOG_REQUESTS=False
The script will expect to connect to your Plex Server using your Plex URL
and Plex Token
Options (Finding a Token).
-
Environment Variables:
-
PLEX_URL=http://192.168.1.12:32400
-
PLEX_TOKEN=123456789
-
-
Shell Commands:
-
-u "http://192.168.1.12:32400"
or--url "http://192.168.1.12:32400"
-
-t "123456789"
or--token "123456789"
-
The only other required Option is the Plex Path
Option which is the Plex Config Directory containing the servers Metadata including Cache
, Metadata
, and Plug-in Support
.
To set the Plex Path
for the run:
-
Environment Variable:
PLEX_PATH=C:\Plex Media Server
-
Shell Command:
-p "C:\Plex Media Server"
or--plex "C:\Plex Media Server"
Will also check /plex
relative to the base directory of the script if neither of the above are specified.
How Plex Image Cleanup runs depends on the Mode
Option that's currently set for that run.
Here, "unused images" refers to unused uploaded images as described above.
-
report
: Reports statistics on unused images [count, size] but takes no action on them [like moving or deleting]. -
move
: Moves unused images to the PIC Restore Directory. From there they can berestore
d orclear
ed. -
restore
: Restores the unused images from the PIC Restore Directory [as created bymove
] to the Metadata Directory. This restores Plex to its state prior to running PIC. -
clear
: Deletes the unused images from the PIC Restore Directory [as created bymove
]. (CANNOT BE UNDONE) -
remove
: Deletes the unused images from the Metadata Directory immediately, without the stop in the PIC Restore Directory. (CANNOT BE UNDONE) -
nothing
: Does nothing with unused images; no report, no action.
To set the Global Mode
for the run:
-
Environment Variable:
MODE=remove
-
Shell Command:
-m remove
or--mode remove
NOTE: report
is the default mode if you do not specify a mode.
In addition to cleaning the Plex Metadata Directory for custom images the script can clean out your PhotoTranscoder Directory, Empty Trash, Clean Bundles, and Optimize DB.
-
Environment Variable:
PHOTO_TRANSCODER=True
-
Shell Command:
-pt
or--photo-transcoder
-
Environment Variable:
EMPTY_TRASH=True
-
Shell Command:
-et
or--empty-trash
-
Environment Variable:
CLEAN_BUNDLES=True
-
Shell Command:
-cb
or--clean-bundles
-
Environment Variable:
OPTIMIZE_DB=True
-
Shell Command:
-od
or--optimize-db
Discord Webhook URL to send notifications to.
-
Environment Variable:
DISCORD=https://discord.com/api/webhooks/###/###
-
Shell Command:
-d "https://discord.com/api/webhooks/###/###"
or--discord "https://discord.com/api/webhooks/###/###"
Connection Timeout in seconds that's greater than 0.
-
Default:
600
-
Environment Variable:
TIMEOUT=1000
-
Shell Command:
-ti 1000
or--timeout 1000
Sleep Timer between Empty Trash, Clean Bundles, and Optimize DB in seconds that's greater than 0 .
-
Default:
60
-
Environment Variable:
SLEEP=100
-
Shell Command:
-s 100
or--sleep 100
Run with extra trace logs.
-
Environment Variable:
TRACE=True
-
Shell Command:
-tr
or--trace
Run with every request and file action logged.
-
Environment Variable:
LOG_REQUESTS=True
-
Shell Command:
-lr
or--log-requests
Plex Image Cleanup can be run either immediately or on a schedule. The default behavior is to run immediately to run using a schedule simply pass in the Schedule
Option.
Add a Schedule Block to the Schedule
Option to run Plex Image Cleanup using a continuous schedule.
-
Shell Command:
-sc
or--schedule "05:00|weekly(sunday)"
-
Environment Variable:
SCHEDULE="05:00|weekly(sunday)"
Schedule Blocks define how and when the script will run.
Each Schedule Blocks has 2 required parts (time
and frequency
) and 1 optional part (options
) all separated with a |
. (Example: time|frequency
or time|frequency|options
)
You can have multiple Schedule Blocks separated with a ,
(time|frequency,time|frequency|options
).
-
time
: Time in the day the run will occur.-
Time:
HH:MM
24-hour format -
Examples:
00:00
-23:59
-
-
frequency
: Frequency to schedule the run.-
Frequencies:
daily
,weekly(day of week)
, ormonthly(day of month)
-
Examples:
weekly(sunday)
ormonthly(1)
-
-
options
: Options changed for the run in the formatoption=value
, with multiple options separated with a;
.-
Options:
mode
,photo-transcoder
,empty-trash
,clean-bundles
, oroptimize-db
-
Examples:
mode=nothing
orphoto-transcoder=true
-
NOTE: This overrides the currently set global value for just this one scheduled run
-
SCHEDULE=08:00|weekly(sunday)|mode=clear,09:00|weekly(sunday)|mode=move,10:00|monthly(1)|mode=nothing;photo-transcoder=true
The example above is detailed out below to better explain how it works:
-
Run at 8:00 AM on Sundays with the Options:
mode: clear
-
08:00|weekly(sunday)|mode=remove
-
time |frequency |options
-
-
Run at 9:00 AM on Sundays with the Options:
mode: move
-
09:00|weekly(sunday)|mode=move
-
time |frequency |options
-
-
Run at 10:00 AM on the 1st of each month with the Options:
mode: nothing
andphoto-transcoder: true
-
10:00|monthly(1)|mode=nothing;photo-transcoder=true
-
time |frequency |options
-