Automate Plex Library Organization With Scripts
A well-organized Plex library means every file is correctly named, tagged, and sorted — with no duplicates, no unmatched items, and no metadata errors. Doing this manually for thousands of files is impractical. Automation tools handle the tedious work: renaming files to Plex conventions, removing duplicates, managing collections, cleaning stale metadata, and maintaining folder structure. This guide covers the tools and scripts that keep a Plex library organized automatically.
File Renaming
FileBot
FileBot is the standard tool for batch-renaming media files to match Plex naming conventions. It queries TMDB, TheTVDB, and other databases to identify files and renames them according to customizable patterns.
Typical workflow:
- Point FileBot at a directory of unsorted downloads.
- FileBot identifies each file by matching filenames and media information against online databases.
- Review the proposed renames.
- Apply the renames. FileBot moves files into the correct folder structure simultaneously.
FileBot patterns for Plex:
- Movies:
{n} ({y})/{n} ({y})producesInception (2010)/Inception (2010).mkv - TV Shows:
{n}/Season {s00}/{n} - {s00e00} - {t}producesBreaking Bad/Season 01/Breaking Bad - S01E01 - Pilot.mkv
Sonarr and Radarr Auto-Rename
If you use Sonarr (TV) or Radarr (movies) for download management, they rename files automatically during import. Configure the rename pattern in each tool's Settings, Media Management section. Files are renamed before they reach the Plex library — no separate renaming step needed.
Duplicate Detection and Removal
Plex Built-In
Plex can detect duplicates within a library. When multiple files match to the same metadata entry, Plex shows them as versions of the same item. Check for duplicates by browsing a library and looking for items with a version badge.
Automated Duplicate Cleanup
For systematic duplicate management:
- Plex-Meta-Manager (PMM): Includes duplicate detection and reporting. It can identify files that match the same metadata entry and generate reports listing all duplicates with their quality and size.
- Custom scripts: Query the Plex API for all items in a library, group by title and year, and flag groups with more than one file. Output a report for manual review before deleting.
Always review before deleting duplicates. Duplicates may be intentional — different cuts of a movie (theatrical vs director's cut) or different quality versions (1080p and 4K).
Collection Management
Plex-Meta-Manager (PMM)
PMM is the most powerful tool for automated collection management in Plex. It creates, populates, and maintains collections based on rules you define:
- Franchise collections: Automatically group all Marvel movies, all Star Wars films, or any franchise into named collections with custom art.
- Genre collections: Create collections by genre — Horror, Comedy, Sci-Fi — populated automatically as new content is added.
- Award collections: Oscar Best Picture winners, Emmy nominees, organized by year.
- Custom lists: Import from IMDB lists, Trakt lists, or Letterboxd lists. PMM populates collections from these external sources on a schedule.
PMM runs on a schedule (typically daily). Each run updates all collections — adding new items that match and optionally removing items that no longer qualify.
Setup
- Install PMM via Docker or Python.
- Create a configuration file defining your Plex server connection, libraries, and collection definitions.
- Define collections using YAML templates. PMM includes many pre-built templates for common collection types.
- Run PMM manually first to verify collections are created correctly.
- Schedule PMM to run automatically (cron on Linux, Task Scheduler on Windows).
Metadata Cleanup
Unmatched Items
Files that Plex could not match to any database entry appear with generic or missing metadata. Find them by sorting a library by Date Added and looking for items without poster art or with incorrect titles.
Automated approach: query the Plex API for items where the metadata agent returned no match. Script output: a list of file paths that need manual matching or renaming.
Stale Metadata
When files are deleted from disk but Plex retains their database entries, the library accumulates stale items that cannot be played. Clean these with:
- Plex's Empty Trash feature: Settings, Manage, Troubleshooting, Empty Trash for each library.
- Enable automatic empty trash in library settings so stale entries are cleaned during each scan.
Poster and Art Cleanup
Plex downloads and caches poster art, background art, and thumbnails. Over time, this cache can grow to tens of gigabytes — especially with large libraries and chapter thumbnails enabled. Manage it by:
- Disabling chapter thumbnails for libraries where they are not needed.
- Using Plex's Clean Bundles feature in Settings, Manage, Troubleshooting to remove cached data for deleted items.
- Periodically running Optimize Database to compact the database file.
Folder Structure Maintenance
Empty Folder Cleanup
When files are moved or deleted, empty folders remain on disk. These do not affect Plex directly but clutter the filesystem. A simple script removes empty directories:
On Linux: find /media/movies -type d -empty -delete
On Windows, use a PowerShell script that recursively identifies and removes empty directories from the media root.
Permission Fixing
Permission issues cause files to be invisible to Plex. Automate permission fixes with a script that runs after new content is added:
- Set all media directories to 755 (read and execute for all users).
- Set all media files to 644 (read for all users).
- Ensure the Plex service user owns or can read all files.
Scheduled Maintenance
Combine all maintenance tasks into a single scheduled routine:
- Daily: PMM collection update, podcast episode check.
- Weekly: Duplicate scan and report, empty folder cleanup, database optimization.
- Monthly: Full metadata refresh for libraries with known agent issues, clean bundles, review unmatched items report.
Run maintenance during off-peak hours when no one is streaming. Library scans, metadata refreshes, and database operations consume I/O and CPU that can impact active playback.
Monitoring
Tautulli
Tautulli monitors Plex usage and can alert you to organizational issues:
- Files that frequently trigger transcodes may need a format or codec change.
- Content that is never watched may be a candidate for removal.
- Users who consistently experience buffering may need quality adjustments.
Custom Health Checks
Build a script that runs weekly and reports:
- Number of unmatched items per library.
- Files with missing or incorrect metadata.
- Duplicate entries and their total wasted storage.
- Library size changes since last check.
- Any files that have been in the download directory for more than a week without being imported.