TPDB is a powerful Python utility that streamlines the management of movie and TV show posters for your Plex media server. Download, organize, and sync custom artwork from ThePosterDB with intelligent fuzzy matching and automated folder organization.
Perfect for Plex enthusiasts using metadata managers like Kometa (formerly Plex Meta Manager) or managing posters directly in your media library.
TPDB in action - downloading and organizing posters automatically
- Table of Contents
- Why TPDB?
- Key Features
- Installation
- Configuration
- Quick Start
- Usage
- Common Workflows
- Directory Structure
- How It Works
- Troubleshooting
- Contributing
- License
- Acknowledgments
Managing custom posters for a large Plex library can be tedious and time-consuming. TPDB automates the entire workflow:
- No more manual renaming - Intelligent fuzzy matching automatically associates posters with your media
- Batch processing - Handle entire poster sets and collections at once
- Kometa-ready - Organized folder structure works seamlessly with Kometa's poster management
- Interactive & Smart - Confirms matches when uncertain, learns from your corrections
- Beautiful CLI - Modern interface with progress bars, colors, and clear prompts
- Fuzzy Matching: Automatically matches posters to your Plex media using intelligent name normalization
- Collection Handling: Organizes movie collection posters into structured subfolders
- TV Season Support: Proper naming for TV show seasons with zero-padded formatting (Season01, Season02, etc.)
- Direct Downloads: Fetch posters and sets from ThePosterDB URLs
- ZIP Processing: Automatically extracts and organizes poster archives
- Progress Tracking: Beautiful progress bars for downloads and batch operations
- Hard Linking: Create hard links from organized posters to your media folders
- Sync Mode: Update existing poster folders with new artwork
- Unlinked Detection: Find and fix orphaned poster folders
- Fuzzy Search: Identify potential duplicate poster folders
- Threshold-based: Configurable similarity matching (74%+ by default)
- Clean Output: Color-coded results with similarity scores
- Interactive Prompts: Typer-based CLI with intuitive confirmation dialogs
- Rich Formatting: Color-coded output, formatted tables, and clear status messages
- Flexible Filtering: Process specific libraries, folders, or media types
- Python 3.10 or higher - Check your version with
python --version - Plex Media Server - Running and accessible on your network
- ThePosterDB Account (optional) - For downloading premium content
-
Clone the repository:
git clone https://github.com/tahmidul612/tpdb.git cd tpdb -
Install using pip:
# For regular use pip install -e . # For development (includes testing and linting tools) pip install -e .[dev]
Or using uv (recommended for faster installation):
# Install uv first (if not already installed) curl -LsSf https://astral.sh/uv/install.sh | sh # Install dependencies uv sync # For development uv sync --group dev
-
Verify installation:
tpdb --help
You should see the TPDB help menu with available commands and options.
TPDB needs to connect to your Plex server to access library information for intelligent poster matching.
First-time setup:
When you run tpdb for the first time, you'll be prompted to enter:
- Plex Server URL: Your server address (e.g.,
http://192.168.1.100:32400) - Authentication Token: Your Plex token (how to find it)
Saving configuration:
If you choose to save these credentials, TPDB creates a configuration file at:
~/.config/plexapi/config.ini
This eliminates the need to re-enter credentials on subsequent runs.
Manual configuration:
You can also manually create the configuration file:
[auth]
server_baseurl = http://your-server:32400
server_token = your_plex_token_here
First-time configuration - entering Plex server details
Get started with TPDB in just a few commands:
# Download a poster set from ThePosterDB
tpdb download "https://theposterdb.com/set/12345"
# Organize new posters for your Movies library
tpdb -l Movies --action new
# Sync existing TV show posters and link them to media folders
tpdb -l "TV Shows" --action sync --copyThe tpdb command processes posters for your Plex libraries with various options:
tpdb [OPTIONS]Basic examples:
# Process all libraries interactively
tpdb
# Process specific library
tpdb -l Movies
# Process multiple libraries
tpdb -l Movies -l "TV Shows"
# Auto-replace all posters without prompting
tpdb -l Movies --all
# Create hard links to media folders
tpdb -l Movies --copyDownload posters directly from ThePosterDB:
# Using the download subcommand
tpdb download "https://theposterdb.com/set/12345"
# Using the -d flag (allows continued processing)
tpdb -d "https://theposterdb.com/set/12345" -l Movies --action newThe downloaded files are automatically saved to your poster directory and can be immediately organized.
Find and identify duplicate poster folders:
# Search default directory (/data/Posters)
tpdb find-dupes
# Search specific directory
tpdb find-dupes /path/to/your/postersOutput shows potential duplicates with similarity scores to help you clean up redundant folders.
| Option | Short | Description | Default |
|---|---|---|---|
--libraries <names> |
-l |
Specify Plex libraries to process | All libraries |
--action <new|sync> |
Process new posters or sync existing folders | new |
|
--unlinked |
-u |
Find and process unlinked poster folders | false |
--force |
-f |
Force rename without matching to media | false |
--filter <string> |
Filter source folders by string match | None | |
--all |
-a |
Replace all posters without prompting | false |
--copy |
-c |
Hard link posters to media folders | false |
--download <url> |
-d |
Download from ThePosterDB before processing | None |
Action Modes:
new(default): Processes new poster files and ZIP archives, organizing them into the proper folder structuresync: Reorganizes existing poster folders, useful after manually adding files or updating naming conventions
Perfect for adding new poster collections to your library:
# Download a complete collection set
tpdb download "https://theposterdb.com/set/12345"
# Organize the downloaded set for your Movies library
tpdb -l Movies --action new
# Copy the organized posters to your media folders
tpdb -l Movies --copyWhen you've manually added posters or want to reorganize:
# Reorganize existing TV show posters
tpdb -l "TV Shows" --action sync
# Sync and link to media folders
tpdb -l "TV Shows" --action sync --copyClean up orphaned poster folders that don't match any media:
# Find unlinked posters in Movies library
tpdb -l Movies --unlinked
# The tool will prompt you to match or rename each unlinked folderMaintain a clean poster directory:
# Find duplicates in your poster directory
tpdb find-dupes /data/Posters
# Review the list and manually remove duplicates
# (TPDB identifies them but doesn't auto-delete for safety)Process specific poster folders:
# Only process folders matching "Marvel"
tpdb -l Movies --filter "Marvel"
# Force organize all matching folders without prompts
tpdb -l Movies --filter "Marvel" --allTPDB organizes your posters into a clean, hierarchical structure optimized for Kometa and Plex:
/data/Posters/ # Default poster root directory
├── Movies/ # Movie library posters
│ ├── Custom/ # Individual movie posters (catch-all)
│ │ ├── The Matrix (1999)/
│ │ │ └── poster.jpg
│ │ ├── Inception (2010)/
│ │ │ └── poster.jpg
│ │ └── Interstellar (2014)/
│ │ └── poster.jpg
│ │
│ ├── Marvel Cinematic Universe/ # Collection posters
│ │ ├── Iron Man (2008)/
│ │ │ └── poster.jpg
│ │ ├── The Avengers (2012)/
│ │ │ └── poster.jpg
│ │ └── Avengers Endgame (2019)/
│ │ └── poster.jpg
│ │
│ └── The Dark Knight Trilogy/ # Another collection
│ ├── Batman Begins (2005)/
│ │ └── poster.jpg
│ ├── The Dark Knight (2008)/
│ │ └── poster.jpg
│ └── The Dark Knight Rises (2012)/
│ └── poster.jpg
│
├── TV Shows/ # TV series posters
│ ├── Breaking Bad/
│ │ ├── poster.jpg # Show poster
│ │ ├── Season01.jpg # Season 1 poster
│ │ ├── Season02.jpg # Season 2 poster
│ │ ├── Season03.jpg
│ │ ├── Season04.jpg
│ │ ├── Season05.jpg
│ │ └── Season00.jpg # Specials
│ │
│ ├── Game of Thrones/
│ │ ├── poster.jpg
│ │ ├── Season01.jpg
│ │ ├── Season02.jpg
│ │ └── ...
│ │
│ └── The Office/
│ ├── poster.jpg
│ └── Season01.jpg
│
└── Archives/ # Processed ZIP files
├── marvel-posters-set.zip
├── dc-collection.zip
└── tv-shows-bundle.zip
- Movies: Organized into collection folders or "Custom" for standalone films
- TV Shows: Seasons use zero-padded naming (Season01, Season02, etc.)
- Collections: Each movie in a collection gets its own subfolder
- Archives: ZIP files are moved here after extraction to keep directories clean
- Naming: All poster files are renamed to
poster.jpgfor consistency
TPDB uses intelligent fuzzy matching to automate poster organization:
Before matching, TPDB normalizes media and poster names:
- Removes years, punctuation, and "set by" text
- Converts to lowercase for comparison
- Strips extra whitespace
Example: "The Matrix (1999) set by UserXYZ" → "the matrix"
Uses the rapidfuzz library with configurable thresholds:
- Library matching: 70%+ similarity for directory discovery
- Media matching: Token-based matching for poster-to-media association
- Duplicate detection: 74%+ similarity for finding duplicates
When matches are uncertain, TPDB prompts for confirmation:
- Shows match score with color coding (green for high confidence, yellow/red for lower)
- Offers options: Accept match, Force organization, or Skip
- Learns from your decisions to improve future matches
Once matched, TPDB:
- Creates proper folder structure
- Renames posters to standard format
- Organizes collections into subfolders
- Moves processed archives to Archives directory
With the --copy flag, creates hard links:
- Links organized posters to actual media folders
- Plex can read posters directly from media directories
- No file duplication (hard links share disk space)
- Verify your Plex server is running and accessible
- Check the server URL in
~/.config/plexapi/config.ini - Ensure your authentication token is valid
- Try accessing Plex web interface from the same machine
- Check that library names match between TPDB and Plex
- Use the
--filteroption to narrow down the search - Try
--forcemode to organize without matching - Verify poster file names are reasonably similar to media names
- Ensure you have write permissions to both poster and media directories
- Hard links require both directories to be on the same filesystem
- Consider using symbolic links instead (requires code modification)
- Adjust the similarity threshold if needed (default is 74%)
- Check that folder names are similar enough for fuzzy matching
- Verify you're searching the correct directory
- Check existing issues: GitHub Issues
- Open a new issue: Provide details about your setup and error messages
- Discussion forum: Ask questions in GitHub Discussions
- Logs: Run with verbose output and include relevant error messages
We welcome contributions! Please see CONTRIBUTING.md for:
- Development environment setup
- Coding standards and conventions
- Testing guidelines
- Pull request process
- Commit message format
This project is licensed under the MIT License - see the LICENSE file for details.
- ThePosterDB - Excellent source for high-quality custom posters
- Kometa - Powerful Plex metadata manager that inspired this tool
- PlexAPI - Python bindings for the Plex API
- Typer - Modern CLI framework
- Rich - Beautiful terminal formatting
- RapidFuzz - Fast fuzzy string matching
Made with ❤️ by Tahmidul Islam
Star ⭐ this repository if you find it helpful!