[](https://github.com/meisnate12/Plex-Image-Cleanup/releases)
[](https://hub.docker.com/r/meisnate12/plex-image-cleanup)
Your Plex folders are growing out of control. You use overlays from [Plex Meta Manager](https://github.com/meisnate12/Plex-Meta-Manager) (PMM) or upload lots of custom art from [Title Card Maker](https://github.com/CollinHeist/TitleCardMaker) (TCM) that you no longer want to use or need to eliminate. You don't want to perform the [plex dance](https://www.plexopedia.com/plex-media-server/general/plex-dance/) if you can avoid it. This script will free up gigs of space....
Special Thanks to [bullmoose20](https://github.com/bullmoose20) for the original [Plex Bloat Fix](https://github.com/bullmoose20/Plex-Stuff#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:
1. Running on a system as a Python script [we will refer to this as a "local" install]
2. 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.
### Install Walkthroughs
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](https://metamanager.wiki/en/latest/home/installation.html#install-walkthroughs).
At this point Plex-Image-Cleanup has been installed, and you can verify installation by running:
```shell
python plex_image_cleanup.py
```
### Docker Install Overview
#### Docker Run:
```shell
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 folder where your .env and other files are.
* Change `<PATH_TO_PLEX>` to the folder where your Plex Folder is (It contains folders: 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](https://www.docker.com/101-tutorial/).
```shell
docker run -v "X:\Media\Plex Image Cleanup\config:/config:rw" -v "X:\Plex Media Server:/plex:rw" meisnate12/plex-image-cleanup
```
#### Docker Compose:
Example Docker Compose file:
```yaml
version: "2.1"
services:
plex-meta-manager:
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
```
#### Dockerfile
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](https://hub.docker.com/r/meisnate12/plex-image-cleanup).
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](https://github.com/meisnate12/Plex-Meta-Manager) or [TitleCardMaker](https://github.com/CollinHeist/TitleCardMaker).
It is recommended to schedule Plex Image Cleanup after the above tools or Plex's Scheduled Tasks.
The only required Option is the `Plex Path` Option which is the Plex Config Folder 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.
#### Mode
How Plex Image Cleanup runs depends on the `Mode` Option that's currently set for that run.
*`report`: Metadata Directory File changes will be reported but not performed.
*`move`: Metadata Directory Files will be moved to the PIC Restore Directory. (CAN BE RESTORED)
*`restore`: Restores the Metadata Directory Files from the PIC Restore Directory.
*`clear`: Clears out the PIC Restore Directory. (CANNOT BE RESTORED)
*`remove`: Metadata Directory Files will be removed. (CANNOT BE RESTORED)
*`nothing`: Metadata Directory Files will not even be looked at.
To set the Global `Mode` for the run:
* **Environment Variable:** `MODE=remove`
* **Shell Command:** `-m remove` or `--mode remove`
### Database
The script needs to query the server's plex database to make sure it doesn't remove actively selected images.
#### Download From Plex API
By default, the script will expect to connect to your Plex Server to download the Database using your `Plex URL` and `Plex Token` Options ([Finding a Token](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-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"`
#### Copy From Local
Alternatively the database can be copied from your local config folder you supplied in the [`Plex Path`](#plex-path) Option by using the `Local DB` Option.
* **Environment Variable:** `LOCAL_DB=True`
* **Shell Command:** `-l` or `--local`
**IMPORTANT! When Copying the Local Database, it is recommended to restart Plex before running this script and to make sure Plex is idle.**
Restarting allows for all temp SQLite files to be written to the primary Plex DB ensuring that all currently selected posters are properly known and preserved.
The script will not run when the temp SQLite files are found. To ignore this error, use the `Ignore Running` Option.
* **Environment Variable:** `IGNORE_RUNNING=True`
* **Shell Command:** `-i` or `--ignore`
#### Use Existing
A previously downloaded or copied database can be used if it's less than 2 hours old by using the `Use Existing` Option. If the database is more than 2 hours old a new one will be downloaded or copied.
* **Environment Variable:** `USE_EXISTING=True`
* **Shell Command:** `-e` or `--existing`
### Other Operations
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.
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)"`
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`).
