DOCSEARCHbyAlgolia
Submit Docs

ImageMaid Documentation

repository·master·Indexed 19 days ago

https://github.com/kometa-team/imagemaid

A cleanup utility for Plex users to reclaim disk space by removing unused posters, backgrounds, and title cards, specifically those generated by Kometa or TitleCardMaker. ImageMaid also supports standard Plex maintenance tasks including database optimization, bundle cleaning, emptying trash, and cleaning the PhotoTranscoder directory. It can be deployed via Docker or installed locally using Python 3.11 or later.

Tokens
2.1K
Snippets
5
Records
11
Agent score
15%

What's inside ImageMaid

  1. ImageMaid Overview

    master

    ImageMaid is a utility designed to free up disk space in Plex environments by removing unused image assets. It targets overlays from Kometa or custom art from Title Card Maker (TCM) that are no longer needed, helping users avoid the "plex dance" when cleaning up metadata.

    In addition to image cleanup, it can perform Plex operations such as:

    • Emptying Trash
    • Cleaning Bundles
    • Optimizing the Database
    • Cleaning the PhotoTranscoder Directory

  2. Configure Plex Database Access

    master

    ImageMaid queries the Plex database to avoid removing actively selected images. You can access the database in two ways:

    1. Download via Plex API (Default)

    Connects to your server to download the database.

    • Environment Variables: PLEX_URL, PLEX_TOKEN
    • Shell Commands: -u "<url>" / --url "<url>" and -t "<token>" / --token "<token>"

    2. Copy from Local Config

    Copies the database directly from your Plex Path.

    • Environment Variable: LOCAL_DB=True
    • Shell Command: -l or --local

    IMPORTANT: When using LOCAL_DB, it is recommended to restart Plex and ensure it is idle so all temp SQLite files are written to the primary DB. If temp files are found, the script will error unless you use the Ignore Running option (-i or IGNORE_RUNNING=True).

    Use Existing Database

    Use a previously downloaded/copied database if it is less than 2 hours old.

    • Environment Variable: USE_EXISTING=True
    • Shell Command: -e or --existing

  3. Install ImageMaid via Docker (Recommended)

    master

    Running ImageMaid as a Docker container is the recommended installation method as it avoids system conflicts and the need to manage Python dependencies manually. You must mount two persistent volumes: one for your configuration files (like .env) and one for your Plex Media Server data directory.

    Important: The Plex directory must contain the Cache, Metadata, and Plug-in Support directories.

    Docker Run

    Use the following command structure, replacing the placeholders with your actual paths:

    docker run -v <PATH_TO_CONFIG>:/config:rw -v <PATH_TO_PLEX>:/plex:rw kometateam/imagemaid

    If your paths contain spaces, wrap them in quotation marks.

    Docker Compose

    You can also use Docker Compose with the following configuration:

    services:
  imagemaid:
    image: kometateam/imagemaid
    container_name: imagemaid
    environment:
      - TZ=TIMEZONE #optional
    volumes:
      - /path/to/config:/config
      - /path/to/plex:/plex
    restart: unless-stopped
    docker run -v "X:\Media\ImageMaid\config:/config:rw" -v "X:\Plex Media Server:/plex:rw" kometateam/imagemaid

  4. Configure Global Options in ImageMaid

    master

    ImageMaid allows you to configure its behavior using three methods, applied in the following priority order:

    1. Environment Variables: Set directly in your shell or system.
    2. .env File: Add variables to a file named .env in the config/ directory. Note that example.env is provided for reference but is not read by the script.
    3. Shell Commands: Pass flags directly when launching the script.

    Example .env configuration:

    PLEX_PATH=C:\Plex Media Server
MODE=report
SCHEDULE=
PLEX_URL=http://192.168.1.12:32400
PLEX_TOKEN=123456789
OVERLAYS_ONLY=False
DISCORD=https://discord.com/api/webhooks/###/###
TIMEOUT=600
NO_VERIFY_SSL=False
SLEEP=60
IGNORE_RUNNING=False
LOCAL_DB=False
USE_EXISTING=False
PHOTO_TRANSCODER=False
EMPTY_TRASH=False
CLEAN_BUNDLES=False
OPTIMIZE_DB=False
TRACE=False
LOG_REQUESTS=False
    PLEX_PATH=C:\Plex Media Server
MODE=report
...

  5. Set up a Continuous Schedule

    master

    To run ImageMaid on a schedule instead of immediately, use the SCHEDULE option. A schedule consists of one or more Schedule Blocks separated by commas.

    Each block follows the format: time|frequency|options (Note: options are optional).

    Block Components

    • time: HH:MM (24-hour format).
    • frequency: daily, weekly(day of week), or monthly(day of month).
    • options: option=value pairs separated by ;. This overrides global settings for this specific run. Supported options: mode, photo-transcoder, empty-trash, clean-bundles, or optimize-db.

    Example Schedule

    SCHEDULE=08:00|weekly(sunday)|mode=clear,09:00|weekly(sunday)|mode=move,10:00|monthly(1)|mode=nothing;photo-transcoder=true

    This example performs:

    1. 08:00 Sunday: Runs in clear mode.
    2. 09:00 Sunday: Runs in move mode.
    3. 10:00 1st of Month: Runs in nothing mode but enables photo-transcoder.

  6. Best practices for running ImageMaid

    master

    ImageMaid is designed to clean up unused posters, backgrounds, and title cards. To prevent conflicts, ensure that no other tools are modifying image assets while ImageMaid is running.

    Avoid running these tools simultaneously with ImageMaid:

    Recommended Scheduling Pattern: Run ImageMaid after your other media management tasks have completed. For example:

    • 02:00-05:00: Plex Scheduled Tasks
    • 05:00-07:00: Kometa
    • 07:00-09:00: ImageMaid

    Performance Tip: For better performance, run ImageMaid locally on the same machine/storage where the files reside rather than accessing them over a network share.

  7. Install ImageMaid locally via Python

    master

    If you prefer a local installation, you must have Python 3.11 or later installed. It is highly recommended to use a virtual environment.

    1. Clone the repository:
      git clone https://github.com/Kometa-Team/ImageMaid
cd ImageMaid
    2. Install dependencies:
      pip install -r requirements.txt
      If the installation fails, try: pip install -r requirements.txt --ignore-installed
    3. Verify the installation by running:
      python imagemaid.py
    git clone https://github.com/Kometa-Team/ImageMaid
cd ImageMaid
pip install -r requirements.txt
python imagemaid.py

  8. Set the Plex Path

    master

    The Plex Path is the only required option. It must point to the Plex Config Directory containing the Cache, Metadata, and Plug-in Support folders.

    • Environment Variable: PLEX_PATH
    • Shell Command: -p "<path>" or --plex "<path>"

    If neither is specified, the script checks for a /plex directory relative to its base directory.

    --plex "C:\Plex Media Server"

  9. Configure the Execution Mode

    master

    The Mode determines what action ImageMaid takes regarding Metadata Directory files:

    ModeDescription
    reportReports changes in the Metadata Directory without performing actions.
    moveMoves files to the ImageMaid Restore Directory (Can be restored).
    restoreRestores files from the ImageMaid Restore Directory.
    clearClears the ImageMaid Restore Directory (Cannot be restored).
    removeDeletes Metadata Directory files (Cannot be restored).
    nothingNo files are inspected.
    • Environment Variable: MODE
    • Shell Command: -m <mode> or --mode <mode>

  10. Configure Other Global Options

    master

    Additional settings for fine-tuning ImageMaid:

    OptionDescriptionEnv VarShell Command
    Overlays OnlyOnly removes Kometa Overlay images.OVERLAYS_ONLY=True-oo or --overlays-only
    Discord URLWebhook for notifications.DISCORD=<url>-d "<url>" or --discord "<url>"
    TimeoutConnection timeout in seconds (Default: 600).TIMEOUT=<sec>-ti <sec> or --timeout <sec>
    No Verify SSLTurn off SSL verification.NO_VERIFY_SSL=True-nv or --no-verify-ssl
    SleepSeconds between cleanup tasks (Default: 60).SLEEP=<sec>-s <sec> or --sleep <sec>
    TraceEnable extra trace logs.TRACE=True-tr or --trace
    Log RequestsLog every request and file action.LOG_REQUESTS=True-lr or --log-requests

  11. Configure Additional Cleanup Operations

    master

    Beyond metadata cleaning, you can trigger these specific operations:

    OperationEnvironment VariableShell Command
    Photo TranscoderPHOTO_TRANSCODER=True-pt or --photo-transcoder
    Empty TrashEMPTY_TRASH=True-et or --empty-trash
    Clean BundlesCLEAN_BUNDLES=True-cb or --clean-bundles
    Optimize DBOPTIMIZE_DB=True-od or --optimize-db