Plex Media Assets Downloader

A Python script that downloads poster and background (fanart) images from your Plex Media Server and saves them as local files alongside your media. Also exports all your Plex collections with full metadata for backup and recreation.

What This Does

• Downloads Images: Saves poster.jpg and fanart.jpg files in your movie, TV show, and music folders
• Exports Collections: Backs up all collection artwork and metadata to JSON
• Incremental Updates: After the first run, only downloads new or changed items (runs in seconds instead of hours)
• Smart Caching: Tracks which images have been downloaded to avoid re-downloading unchanged files
• Works With: Movies, TV Shows (including seasons), and Music libraries

Why You'd Want This

• Media Manager Compatibility: Local poster/fanart files work with Kodi, Emby, Jellyfin, and other media managers
• Collection Backup: Save your carefully curated collections in case you need to rebuild your Plex server
• Offline Access: Keep artwork even if Plex's metadata sources are unavailable
• Cross-Platform: Migrate your artwork between different media server platforms

Requirements

• Python 3.12+ (3.8+ will probably work)
• Plex Media Server with local access
• requests library: pip install requests
• Windows, Mac, or Linux

Quick Start

1. Install Python (if not already installed)

   • Download from python.org
   • During installation, check "Add Python to PATH"

2. Install the requests library

   pip install requests

3. Download this project

   • Click the green "Code" button → "Download ZIP"
   • Extract to a folder like C:\Plex_Downloader

4. Get your Plex Token

   • Open plex.tv in your web browser
   • Play any movie or show
   • Click the three dots (...) → "Get Info" → "View XML"
   • In the URL bar, find X-Plex-Token=XXXXX
   • Copy everything after the = sign

5. Configure the script

   • Open plex_media_downloader.py in a text editor
   • Find the CONFIGURATION section (around line 20)
   • Update these settings:
     • PLEX_TOKEN: Paste your token
     • LIBRARY_FOLDER_MAPPING: Map your Plex library names to local folders
     • BASE_PATH: Set to your Plex_Downloader folder location

6. Create folder structure

   C:\Plex_Downloader\
   ├── Scripts\          (put the .py script here)
   ├── Logs\
   │   └── archive\
   └── Collections\
       └── Archive\

7. Run the script

   cd C:\Plex_Downloader\Scripts
   python plex_media_downloader.py

   First run will take HOURS for large libraries. Subsequent runs take seconds to minutes.

Detailed Documentation

See the Complete Setup Guide for:

• Detailed installation instructions
• Configuration examples
• Troubleshooting tips
• Scheduling automatic runs
• Advanced settings

Configuration Example

# Your Plex server details
PLEX_URL = "http://127.0.0.1:32400"
PLEX_TOKEN = "your_actual_token_here"

# Map Plex library names to local folders
LIBRARY_FOLDER_MAPPING = {
    "Movies": r"D:\Media\Movies",
    "TV Shows": r"D:\Media\TV Shows",
    "Christmas Movies": r"D:\Media\Seasonal\Christmas",
}

# Where to save logs and collections
BASE_PATH = r"C:\Plex_Downloader"

What Gets Created

After running, you'll have:

In Media Folders

D:\Media\Movies\The Matrix (1999)\
├── The Matrix (1999).mkv
├── poster.jpg          ← Downloaded by this script
├── fanart.jpg          ← Downloaded by this script
├── poster.jpg.url_cache
└── fanart.jpg.url_cache

In Collections Folder

C:\Plex_Downloader\Collections\
├── Movies - Marvel Cinematic Universe.jpg
├── Movies - Marvel Cinematic Universe_fanart.jpg
├── collections_data.json  ← All collection metadata
└── Archive\
    └── collections_data_20241016_143022.json

In Logs Folder

C:\Plex_Downloader\Logs\
├── plex_downloader.log
├── plex_unmatched_items.log
└── archive\
    ├── plex_downloader_20241015_030000.log
    └── plex_downloader_20241014_030000.log

Scheduling Automatic Runs

Windows (Task Scheduler)

Use the included plex_poster_downloader.bat file:

1. Edit the .bat file to set your paths
2. Open Task Scheduler
3. Create Basic Task:
   • Name: Plex Media Downloader
   • Trigger: Daily at 3:00 AM
   • Action: Start a program
   • Program: Path to your .bat file

Linux/Mac (Cron)

# Edit crontab
crontab -e

# Add this line (runs daily at 3 AM)
0 3 * * * /usr/bin/python3 /path/to/plex_media_downloader.py

How Incremental Updates Work

After the first run:

• Script tracks the last update time for each library
• Only processes items that changed since last run
• Checks URL cache files to see if image URLs changed
• Typical run time: 30 seconds to 5 minutes (vs hours for first run)

Troubleshooting

"No libraries found"

• Check your PLEX_URL and PLEX_TOKEN
• Make sure Plex server is running
• Try accessing http://127.0.0.1:32400/web in your browser

"All items skipped"

• Verify LIBRARY_FOLDER_MAPPING paths are correct
• Check that folders actually exist
• Look at plex_unmatched_items.log for details

Script is very slow

• First run is always slow (normal)
• Increase INITIAL_TIMEOUT_SECONDS if you get timeouts
• Check your network connection to Plex server

Timeout errors

• Increase INITIAL_TIMEOUT_SECONDS from 120 to 300
• Large libraries need more time for initial queries

See the Setup Guide for more troubleshooting help.

Storage Requirements

Typical file sizes:

• Movie poster: 200-500 KB
• Movie fanart: 300-800 KB
• TV show poster: 200-400 KB per season

Example:

• 1,000 movies: ~700 MB
• 100 TV shows (10 seasons each): ~600 MB
• 500 collections: ~350 MB
• Total: ~1.7 GB

Important Files

Never Delete:

• plex_downloader_settings.json - Tracks what's been processed
• .url_cache files in media folders - Prevents re-downloads

Safe to Delete:

• Log files (they'll be recreated)
• Archived logs (old history only)

Backup These:

• collections_data.json - All your collection info
• plex_downloader_settings.json - Script state

Advanced Features

• Force Re-Download: Edit plex_downloader_settings.json and set "force_cache_init": true
• Custom Image Quality: Adjust HIGH_QUALITY_PARAMS and FANART_QUALITY_PARAMS
• 404 Blacklist: Automatically tracks and skips broken image URLs
• Graceful Shutdown: Press Ctrl+C to stop safely (finishes current operation)

Contributing

Found a bug or have a suggestion? Open an issue on GitHub!

License

This project is provided as-is for personal use. Feel free to modify and share.

Credits

Created to solve the problem of backing up Plex artwork and making it available to other media managers.

Version History

• v1.0 - Initial release
  • Movie, TV show, and music support
  • Incremental update system
  • Collection export with metadata
  • URL caching for efficiency

Need Help? Check the Complete Setup Guide or open an issue on GitHub.