(Multi)mediasorter

Inspired by https://github.com/joshuaboniface/mediasorter, rewritten from scratch with asyncio, enhanced pattern matching and packaged for easier installation/usage.

"mediasorter is a tool to automatically "sort" media files from a source naming format into something nicer for humans to read/organize, and for tools like Jellyfin to parse and collect metadata for. It uses The Movie DB for movie metadata and TVMaze for TV metadata to obtain additional information, then performs the "sort" via a user-selectable mechanism. In this aspect it seeks to be a replacement for FileBot and other similar tools."

See the mediasorter-server project for a simple (yet useful) web app frontend.

Installation

Install from PyPI.
```
pip install multimediasorter
```
Bootstrap a default configuration file, you will be prompted for your TMDB api key.
```
mediasorter --setup
```
Edit the configuration file with your TMDB API key (otherwise only TV shows searches will work).
See --help for more details.
```
mediasorter --help
```

Usage

CLI args

You can specify a folder-to-be-sorted manually with the first positional argument. By default, mediasorter tries to figure out the media type (auto), it then sorts TV show and movies to their respective folders (if both arguments are used) or into a one single common folder (if only single destination folder is specified).

mediasorter sort -m auto ./tests/test_data/ ~/Media/Series ~/Media/Movies

Configuration

You can preconfigure folders to be sorted in your configuration YAML. See the info command to find out what is configured and where to find your configuration file.

mediasorter info

Then simply append entries to the scan_sources section

# Use this to configure what directories should be sorted instead of the CLI argument(s).
scan_sources:

  - src_path: ~/Downloads-01
    media_type: auto  # force only a specific media type tv/movie/auto
    tv_shows_output: ~/Media/TV  # where to put recognized TV shows
    movies_output: ~/Media/Movies

  - src_path: ~/Downloads-02
    media_type: auto
    tv_shows_output: ~/Media/TV
    movies_output: ~/Media/Movies

Search Overrides

Sometimes, the name of a piece of media, as extracted from the file, will not return proper results from the upstream metadata providers. If this happens, mediasorter includes an option in the configuration file to specify search overrides. For example, the TV show "S.W.A.T." does not return sensible results, so it can be overridden like so:

search_overrides:
   "s w a t": "swat"
   # ...

There's also a public .yaml with already discovered overrides in the root of this repository. mediasorter uses it in conjunction with all the entries in the local configuration file. PRs are welcomed!

Metadata

Release files for multimediasorter 2.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for multimediasorter 2.1.0
File	Interpreter	ABI	Platform	Reset
multimediasorter-2.1.0-py3-none-any.whl 25.9 kB Sep 10, 2026	Python 3	none	any	Details

Release files / multimediasorter-2.1.0-py3-none-any.whl

Download URL	multimediasorter-2.1.0-py3-none-any.whl
Size	25.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f0ce14af0c2076e4c3a5960de1e57bf4612b4fd982e628482afbc90933993a0d`
BLAKE2b-256 checksum How to use checksums	`5eff861b48fd954400a968887ea0ab4d4ab6374046b1a0862698f5e85344291c`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Fedora Linux","version":"44","id":"","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`