Plex Auto Trash

Automatically empty the trash in all of your Plex libraries.

If you disable automatic trash emptying (and you probably should) trash still accumulates and must be emptied manually.
This tool will automatically empty the trash of every library using two simple rules:

  • Do not empty trash if the library is currently scanning.
  • Do not empty trash until X minutes have passed since last scan (where X is configurable).

Available as a standalone binary and Docker container.


You will need a Plex authentication token to use this tool.
See Plex’s documentation on how to obtain yours.

From there, you can access the tool in one of two ways:


Install on Mac with:

$ brew install JakeWharton/repo/plex-auto-trash

which will put the plex-auto-trash on your shell path (assuming Homebrew is set up correctly).

For other platforms, download ZIP from
latest release
and run bin/plex-auto-trash or bin/plex-auto-trash.bat.

Command-line instructions

Usage: plex-auto-trash [OPTIONS] [LIBRARY]...

  Empty the trash in all of your Plex libraries.

  --base-url URL          Base URL of Plex server web interface (e.g.,
  --token TOKEN           Plex authentication token. See:
Finding an authentication token / X-Plex-Token
--scan-idle MINUTES Minimum amount of time (in minutes) since a library scan to empty its trash (default: 5) --exclude-library NAME Name of libraries to exclude. Mutually exclusive with LIBRARY arguments. -h, --help Show this message and exit Arguments: LIBRARY Name of libraries to scan. All libraries will be scanned if none specified. Mutually exclusive with --exclude-library

The --base-url and --token arguments are required.

When run, the tool will traverse all of your Plex libraries to get their folder paths. Then, it will
obtain every file in those paths and compare it to items in that Plex library. Any files which are
not indexed by Plex will be output, and the command will have an exit code of 1.

$ plex-auto-trash --base-url http://plexms:32400/ --token MY_TOKEN
[1/2] Emptying trash: Movies... Done
[2/2] Emptying trash: TV... Done


A container which runs the binary is available from Docker Hub and GitHub Container Registry.

  • jakewharton/plex-auto-trash
    Docker Image Version
    Docker Image Size


Start this container and point it at your Plex server with the PLEX_BASE_URL and PLEX_TOKEN environment variables.

$ docker run -d \
    -e "PLEX_BASE_URL=http://plexms:32400" \
    -e "PLEX_TOKEN=abcdef123456" \

For Docker Compose, add it as an additional service:

    container_name: plex-auto-trash
    image: jakewharton/plex-auto-trash:1
    restart: unless-stopped
      - "PLEX_BASE_URL=http://plexms:32400"
      - "PLEX_TOKEN=abcdef123456"

The container will empty trash at 12 minutes past the hour, every hour by default.
This should hopefully avoid collision with other tools and scheduled library scans.
To change when it runs, specify the CRON environment variable with a valid cron specifier.
For help creating a valid cron specifier, visit

The default minimum time since last scan (called “idle time”) is 5 minutes.
Specify an integer value in the SCAN_IDLE environment variable to change this value.

To be notified when sync is failing visit, create a check, and specify
the ID to the container using the HEALTHCHECK_ID environment variable.


To run the latest code build with ./gradlew installDist. This will put the application into
build/install/plex-auto-trash/. From there you can use the
command-line instructions to run.

The Docker containers can be built with docker build ., which also runs the full set of checks
as CI would.


Copyright 2021 Jake Wharton

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.


View Github