ImageMaid

ImageMaid is an open-source utility from the Kometa Team that identifies and cleans unused images in the Plex metadata directory. Depending on its configured mode, ImageMaid can report, move, restore, or permanently remove unused images. It can also clean the PhotoTranscoder directory and request Plex maintenance operations such as Empty Trash, Clean Bundles, and Optimize Database.

ImageMaid can generate significant disk activity when scanning or removing a large number of files. Schedule it outside peak hours and configure it carefully to comply with Ultra.cc's Fair Usage Policy.

Prerequisites

• Install Plex Media Server on your Ultra.cc service.
• Install Python 3.11 using the Install Python Using Pyenv guide.
• Load Pyenv into your current shell after installing Python:

source ~/.profile

Install ImageMaid

• Connect to your Ultra.cc service through SSH.
• Execute the following command:

bash <(wget -qO- <https://scripts.ultra.cc/comm-v1/ImageMaid/main.sh>)

• Type 1 and press ENTER.
• Wait for the installer to clone ImageMaid, install its Python dependencies, create its configuration, and start its systemd service.
• Check the service after installation:

systemctl --user status imagemaid.service --no-pager

• The installer clones the current master branch of the ImageMaid GitHub repository rather than installing a fixed release.

Configure ImageMaid

• ImageMaid does not have a web interface. Configure it by editing its .env file:

~/scripts/imagemaid/config/.env

• An upstream example containing the available configuration options is located at:

~/scripts/imagemaid/config/example.env

• Stop ImageMaid before editing its configuration:

systemctl --user stop imagemaid.service

• The installer automatically retrieves the Plex configuration path, Plex URL, and Plex token.

• For the complete list of options, see the official ImageMaid configuration documentation.

Choose a Mode

• ImageMaid supports the following modes:
• report: Reports proposed changes without moving or deleting files.
• move: Moves identified files to the ImageMaid restore directory. These files can be restored.
• restore: Restores files from the ImageMaid restore directory.
• clear: Permanently clears the ImageMaid restore directory.
• remove: Permanently removes identified files without first placing them in the restore directory.
• nothing: Does not inspect the Plex metadata images.
• Always use report first. Review the results before using move, clear, or remove.

• For more information, see the official ImageMaid mode documentation.

Review the Default Schedule

• The Ultra.cc community installer currently creates the following schedule:

SCHEDULE=07:00|daily|mode=report,09:00|weekly(sunday)|mode=move,11:00|weekly(sunday)|mode=clear

This schedule causes ImageMaid to:

• Run in report mode daily at 07:00.
• Run in move mode every Sunday at 09:00.
• Run in clear mode every Sunday at 11:00.

• Schedule blocks use the following format:

time|frequency|options

• Multiple schedule blocks are separated by commas:

time|frequency|options,time|frequency|options

• For the complete schedule syntax and available per-run options, see the official ImageMaid scheduling documentation.

Avoid Concurrent Tasks

• Do not run ImageMaid while Kometa, TitleCardMaker, Plex Scheduled Tasks, or another tool is changing posters, backgrounds, title cards, or the Plex database.
• Schedule these tools in separate time windows to avoid conflicting changes. The ImageMaid maintainers provide the following example:
• 00:00–02:00: TitleCardMaker
• 02:00–05:00: Plex Scheduled Tasks
• 05:00–07:00: Kometa
• 07:00–09:00: ImageMaid
• Ensure ImageMaid has permission to move, rename, and delete files within the configured Plex metadata directory.

Manage ImageMaid

Check the Service

• Execute the following command to check whether ImageMaid is running:

systemctl --user status imagemaid.service --no-pager

Stop ImageMaid

systemctl --user stop imagemaid.service

Start ImageMaid

systemctl --user start imagemaid.service

Restart ImageMaid

• Restart ImageMaid after changing its .env configuration:

systemctl --user restart imagemaid.service

Check the Logs

• ImageMaid writes normal application output and errors to separate files:
• Application log: ~/scripts/imagemaid/logs/imagemaid.log
• Error log: ~/scripts/imagemaid/logs/error.log
• Execute the following command to view the last 100 lines of the application log:

tail -n 100 ~/scripts/imagemaid/logs/imagemaid.log

• Execute the following command to view the last 100 lines of the error log:

tail -n 100 ~/scripts/imagemaid/logs/error.log

• To monitor the application log continuously, execute:

tail -f ~/scripts/imagemaid/logs/imagemaid.log

• Press CTRL+C to stop monitoring the log.

Uninstall ImageMaid

• Connect to your Ultra.cc service through SSH.
• Execute the installer again:

bash <(wget -qO- <https://scripts.ultra.cc/comm-v1/ImageMaid/main.sh>)

• Type 2 and press ENTER.
• Wait for the installer to stop and disable the service, remove the service file, and delete the ImageMaid directory.

If you require further assistance, you can open a support ticket here.

• ImageMaid
• Prerequisites
• Install ImageMaid
• Configure ImageMaid
• Choose a Mode
• Review the Default Schedule
• Avoid Concurrent Tasks
• Manage ImageMaid
• Check the Service
• Stop ImageMaid
• Start ImageMaid
• Restart ImageMaid
• Check the Logs
• Uninstall ImageMaid