🎬 Plex Poster Downloader & Manager

A self-hosted web application that allows you to easily browse your Plex libraries and download local poster artwork (poster.jpg) and backgrounds (background.jpg) to any local folder.

This tool is perfect for users who want to switch to "Local Assets" agents, use tools like Kometa (formerly PMM), or simply want a backup of their curated artwork stored alongside their media files.

AI WARNING

THIS SCRIPT WAS GENERATED USING GOOGLE GEMINI! I KNOW THIS CAN BE A TURN OFF FOR SOME BUT HAS BEEN TESTED AND WORKS GREAT! JUST GIVING THIS WARNING NOW AS I KNOW SOME DONT LIKE AI MADE SCRIPTS YOU HAVE BEEN WARNED.

✨ Features

• Plex-Themed Web UI: A dark, responsive interface designed to feel like home for Plex users.

• Global Search: Instantly search for movies or shows across all libraries with autocomplete suggestions.

• Background & Fanart Support: Dedicated tabs to switch between Posters and Backgrounds.

  • Download high-res backgrounds for Movies, Shows, and Seasons.

  • Provider badges (TMDB, Fanart.tv, etc.) to see source quality.

• Automated Scheduler (Cron):

  • Schedule daily or weekly downloads (e.g., "Every Friday at 3:00 AM").

  • Choose specific libraries to target.

  • Modes: Random (fill missing spots), Specific Provider, or Random Provider.

  • Option to auto-download backgrounds alongside posters.

• Flexible Asset Structures: Support for both Asset Folders and Flat naming conventions.

• Migration Tool: Built-in utility to scan and convert your existing downloaded posters between folder structures.

• Download Tracking:

  • Green (✅): Poster already downloaded.

  • Yellow (⚠️): Partial download (e.g., Show has a poster but seasons are missing, or vice versa).

  • Standard: Poster missing.

• Library Management:

  • Supports Movies and TV Shows.

  • Paginated views for large libraries.

  • Hidden Libraries: Easily hide specific libraries (like 4K or Home Videos) via the Settings checklist.

• Authentication: Secure the interface with an admin username/password (can be disabled in Settings).

• Manual Override: Toggle items as "Complete" manually if you don't want to download a poster for them.

📷Screenshots

• Settings

• Homepage

• Library

• Posters

🐳 Docker Installation (Recommended)

The easiest way to run this application is using Docker.

Prerequisites

• Docker

• Docker Compose

1. Create Project Directory

Create a folder on your server and place the compose.yaml file inside it.

2. Configure Volumes

Open compose.yaml and ensure the volumes map to your actual media folders.

services:
  plex-poster-downloader:
    image: ghcr.io/johnfawkes/plex-poster-downloader:latest
    container_name: plex-poster-manager
    restart: unless-stopped
    ports:
      - "5015:5000"
    volumes:
      # Stores config.json and download history
      - ./config:/app/config
      # If using with Kometa, change the first downloaded_posters to the asset directory for kometa
      - ./downloaded_posters:/app/config/downloaded_posters
    environment:
      - DATA_DIR=/app/config
      - PUID=1000  # run `id -u` on your host to get your UID
      - PGID=1000  # run `id -g` on your host to get your GID

3. Run the Container

docker-compose up -d

4. Access the UI

Open your browser and navigate to: http://localhost:5015

🐍 Manual Installation (Python)

If you prefer running it directly on your host machine without Docker.

Prerequisites

• Python 3.11 or higher

• pip

Steps

1. Clone the Repository

git clone https://github.com/johnfawkes/plex-poster-downloader.git
cd plex-poster-downloader

2. Install Dependencies

pip install -r requirements.txt

(Note: Create a virtual environment first if preferred)

3. Run the Script

python plex_poster_downloader.py

4. Access the UI Open http://localhost:5015 in your browser.

⚙️ Configuration

On the first launch, you will be redirected to the Settings page.

1. Authentication: You will be asked to create an Admin Username and Password.

2. Plex Connection:

   • Plex Server URL: e.g., http://192.168.1.10:32400

   • Plex Token: Your X-Plex-Token. How to find your token.

3. Hidden Libraries: You can uncheck libraries you don't want to manage (e.g., Home Videos, Music).

📂 Folder Structure Logic

This tool supports two different naming conventions for saving posters. You can switch between them in Settings and use the Migrate Files tool to automatically reorganize your existing downloads.

1. Asset Folders:

   • Movies: [BaseDir]/Library Name/Movie Name/poster.jpg

   • Shows: [BaseDir]/Library Name/Show Name/poster.jpg

   • Seasons: [BaseDir]/Library Name/Show Name/Season01.jpg

2. No Asset Folders (Flat):

   • Movies: [BaseDir]/Library Name/Movie Name.jpg

   • Shows: [BaseDir]/Library Name/Show Name.jpg

   • Seasons: [BaseDir]/Library Name/Show Name_Season01.jpg

Note: The script creates folders if they don't exist.

🛠️ Troubleshooting

Login loop or Session errors: The app generates a new secret key on every restart for security. If you restart the container, you will need to log in again.

Future Plans

• Add support for titlecards
• Add support for logos
• Add Squareart support
• Add support for backgrounds
• Maybe add manual upploading of assets to the webui for ease of use when you may not have access to the internal filesystem to place them manully
• Add a viewer for just the locally downloaded posters. Seperate it out from the downloader