Skip to content

About

A CLI tool made to make organizing your media for Plex Media Server easy. Normalize names of media files and directories to match the hierarchial requirements that Plex requires.

Topics

Resources

Code of conduct

Security policy

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

Plexer

GitHub Release PyPI - Version

GitHub License Supported Python Versions

GitHub Issues or Pull Requests GitHub Downloads (all assets, all releases)

OpenSSF Scorecard OpenSSF Best Practices

Run Full Suite of Checks and Tests Release

Summary

Plexer is a CLI tool that makes it easy to organize your media for Plex Media Server. It renames media files and directories to match the hierarchical naming that Plex requires.

Features

Support

Currently, Plexer only supports organizing movies and other individual video files.

How It Works

Plexer expects the source directory to contain one subdirectory per movie. For each subdirectory, Plexer:

  1. Infers the movie's name, release year, and edition (e.g. Director's Cut, Extended Edition) from the directory name using heuristics
  2. Prompts you for any metadata it couldn't infer (see --prompt)
  3. Renames the directory to the Plex format, e.g. The.Black.Phone.2021.1080p.WEBRip.x265-RARBG → The Black Phone (2021)
  4. Renames each video, subtitle, and .nfo file inside it to match, e.g. Blade Runner (1982) {edition-Final Cut}.mkv
  5. Deletes any file in the directory that isn't a supported file type (.txt files, images, .DS_Store, etc.)

Files that are already in the correct format are left alone. Symlinks are skipped, and Plexer refuses to rename or delete anything outside of the source directory.

Warning

Plexer renames files and deletes unsupported files in place, inside the source directory. Run it with --dry-run -vv first to preview what it will do, and keep a backup of anything you can't replace.

Roadmap

  • Support for TV Shows (#28)
  • Docker implementations (#29)
  • MacOS support (#30)
  • Windows support (#31)
  • Metadata inference using file/directory info (i.e. analyze the video files to "guess" what the name, year, etc is) (#32)

Install

Docker

The most portable way to install and run Plexer is by using Docker.

Via Container Registry

The easiest way to run Plexer in Docker is by using the public images hosted on container registries. Plexer images are available on both Docker Hub and GitHub Container Registry.

Mount your media directory into the container and pass Plexer's arguments after the image name. Without arguments, the container prints the help text. The container runs as a non-root user (UID/GID 1001), so the mounted directory must be writable by that user.

Docker Hub
docker run --rm -it -v /path/to/media:/media magneticstain/plexer-cli \
  --source-dir /media --destination-dir /media --dry-run -vv
GitHub Container Registry
docker run --rm -it -v /path/to/media:/media ghcr.io/magneticstain/plexer-cli \
  --source-dir /media --destination-dir /media --dry-run -vv

Via Local Image Build

If the container registries are unavailable, you can also build the image locally. Clone this repo, build the Plexer image, and run it.

git clone https://github.com/magneticstain/plexer-cli.git
cd plexer-cli
docker build -t plexer_cli .
docker run --rm -it -v /path/to/media:/media plexer_cli \
  --source-dir /media --destination-dir /media --dry-run -vv

PyPI

Plexer is published on PyPI and requires Python 3.10 or newer. Installing it with pipx or uv keeps it isolated from your other Python packages:

pipx install plexer-cli
# or
uv tool install plexer-cli

This installs the plexer command. Native installs also need libmagic; see Requirements below.

Requirements

Linux and MacOS Native Install

If you've installed Plexer natively (i.e. outside of a Docker container) on Ubuntu, Debian, Fedora, etc., or MacOS, you will also need to install additional dependencies:

Python-Magic

Plexer uses python-magic to detect video files that don't have a recognized file extension. It's installed automatically as a Python dependency, but it depends on the libmagic C library, which isn't. To install this library, follow the installation instructions provided in the python-magic README. For example:

# Debian/Ubuntu
sudo apt-get install libmagic1

# MacOS (Homebrew)
brew install libmagic

The Docker image already includes libmagic.

Usage

The source directory is the directory containing the raw media, with one subdirectory per movie.

usage: plexer [-h] [-v] [--version] -s SOURCE_DIR -d DESTINATION_DIR
              [--prompt {all,none,default}] [--dry-run]

options:
  -h, --help            show this help message and exit
  -v, --verbose         Verbosity (-v, -vv, etc)
  --version             show program's version number and exit
  -s, --source-dir SOURCE_DIR
  -d, --destination-dir DESTINATION_DIR
  --prompt {all,none,default}
                        Behavior to take in regards to user prompts (e.g.
                        correcting names for overwriting files). all = prompt
                        user for every artifact; none = never prompt - just
                        trust the heuristics; default = prompt for incomplete
                        matches only
  --dry-run             Perform a trial run with no changes made

Note

--destination-dir is required, but Plexer doesn't use it yet. All changes are currently made in place, inside the source directory.

Example

# preview the changes first
plexer -s ~/Downloads/movies -d ~/Downloads/movies --dry-run -vv

# then apply them
plexer -s ~/Downloads/movies -d ~/Downloads/movies -v

Prompt Behavior

The --prompt option controls when Plexer asks you to confirm or correct a movie's name, edition, and release year:

Value Behavior
default Prompt only when the name or release year can't be inferred from the directory name
all Prompt for every movie directory, pre-filled with whatever was inferred
none Never prompt; directories whose metadata can't be inferred are skipped

Logging

By default, only warnings and errors are printed. Use -v for informational output and -vv for debug output, which shows each rename and delete operation.

Supported File Types

Plexer keeps and renames the following file types; anything else inside a movie directory is deleted:

Type File extensions
Video .avi, .m2ts, .m4v, .mkv, .mov, .mp4, .mpeg, .mpg, .ts, .webm, .wmv
Subtitles .ass, .idx, .smi, .srt, .ssa, .sub, .vtt
Metadata .nfo

File types are matched by file extension (case-insensitive). As a fallback, any other file that libmagic detects as video (a video/* MIME type) is also kept, so videos with unusual extensions aren't deleted.

Note

[BUG] Each kept file is renamed to the movie's name plus its original extension, e.g. movie.en.srt → Blade Runner (1982).srt. If a directory contains several files with the same extension (e.g. multiple subtitle languages, or a sample video), they are renamed to the same name and only one is kept. See #177.

Support & Feedback

If you run into issues while using Plexer, think you know a way to make it better, or just need help using it, create a new issue and it will be triaged when possible. Additional documentation is available in the project wiki.

To report a security vulnerability, follow the process in SECURITY.md instead of opening a public issue.

Development

Software Stack

Hatch project uv Ruff

For developing with Plexer, there are several tools that are in use:

  1. Build Backend and Packaging:
    1. Hatch
  2. Dependency Management:
    1. uv
  3. Analysis Tools:
    1. Ruff
    2. actionlint
  4. Testing:
    1. Pytest
    2. Tox

Tool versions used for development are pinned in .tool-versions and .python-version.

Getting Started

git clone https://github.com/magneticstain/plexer-cli.git
cd plexer-cli
uv sync
pre-commit install

You'll also need libmagic installed locally (see Requirements).

Coding Standards and Conventions

  • Pre-commit hooks are utilized and managed in .pre-commit-config.yaml
    • For example, ruff is run as part of every commit
    • These pre-commit hooks MUST be installed and utilized by all developers
  • See the Code of Conduct for community guidelines

Testing

  • All functions MUST have unit tests created for them
  • Unit tests live in tests/ and can be run with uv run pytest, or across all supported Python versions along with formatting and linting checks using tox
  • For manual end-to-end testing, tests/bootstrap/bootstrap_plexer_e2e.sh creates sample media in /tmp/plexer-e2e
    • Run it from the repo root, then use the launch configurations in .vscode/launch.json (or run plexer directly) against those directories

About

A CLI tool made to make organizing your media for Plex Media Server easy. Normalize names of media files and directories to match the hierarchial requirements that Plex requires.

Topics

Resources

Code of conduct

Security policy

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages