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.
Currently, Plexer only supports organizing movies and other individual video files.
Plexer expects the source directory to contain one subdirectory per movie. For each subdirectory, Plexer:
- Infers the movie's name, release year, and edition (e.g.
Director's Cut,Extended Edition) from the directory name using heuristics - Prompts you for any metadata it couldn't infer (see
--prompt) - Renames the directory to the Plex format, e.g.
The.Black.Phone.2021.1080p.WEBRip.x265-RARBG→The Black Phone (2021) - Renames each video, subtitle, and
.nfofile inside it to match, e.g.Blade Runner (1982) {edition-Final Cut}.mkv - Deletes any file in the directory that isn't a supported file type (
.txtfiles, 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.
- 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)
The most portable way to install and run Plexer is by using Docker.
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 run --rm -it -v /path/to/media:/media magneticstain/plexer-cli \
--source-dir /media --destination-dir /media --dry-run -vvdocker run --rm -it -v /path/to/media:/media ghcr.io/magneticstain/plexer-cli \
--source-dir /media --destination-dir /media --dry-run -vvIf 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 -vvPlexer 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-cliThis installs the plexer command. Native installs also need libmagic; see Requirements below.
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:
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 libmagicThe Docker image already includes libmagic.
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.
# preview the changes first
plexer -s ~/Downloads/movies -d ~/Downloads/movies --dry-run -vv
# then apply them
plexer -s ~/Downloads/movies -d ~/Downloads/movies -vThe --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 |
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.
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.
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.
For developing with Plexer, there are several tools that are in use:
- Build Backend and Packaging:
- Dependency Management:
- Analysis Tools:
- Testing:
Tool versions used for development are pinned in .tool-versions and .python-version.
git clone https://github.com/magneticstain/plexer-cli.git
cd plexer-cli
uv sync
pre-commit installYou'll also need libmagic installed locally (see Requirements).
- Pre-commit hooks are utilized and managed in
.pre-commit-config.yaml- For example,
ruffis run as part of every commit - These pre-commit hooks MUST be installed and utilized by all developers
- For example,
- See the Code of Conduct for community guidelines
- All functions MUST have unit tests created for them
- Unit tests live in
tests/and can be run withuv run pytest, or across all supported Python versions along with formatting and linting checks usingtox - For manual end-to-end testing,
tests/bootstrap/bootstrap_plexer_e2e.shcreates sample media in/tmp/plexer-e2e- Run it from the repo root, then use the launch configurations in
.vscode/launch.json(or runplexerdirectly) against those directories
- Run it from the repo root, then use the launch configurations in