Skip to main content

A media file organiser

Project description

pypi travis_ci coverage licence code style black

mnamer logo


mnamer (media renamer) is an intelligent and highly configurable media organization utility. It parses media filenames for metadata, searches the web to fill in the blanks, and then renames and moves them.

mnamer terminal recording


Stable Version

$ pip install mnamer

Development Version

$ pip install


If you want to install it using system python (e.g. the one that comes with your OS, not really recommended) and get a permission error you need to use either sudo -H pip ... or pip install --user ....


mnamer target [targets ...] [options] [directives]


mnamer attempts to load options from mnamer.json in the user's configuration directory, .mnamer.json in the current working directory, and then from the command line, also overriding each other in that order.

Option Arguments Description
-b, --batch batch mode; disables interactive prompts
-s, --scene scene mode; replace non ascii-alphanumerics with .
-r, --recurse show this help message and exit
-v, --verbose increases output verbosity
--blacklist pattern ignore files including these words
--max_hits number limits the maximum number of hits for each query
--extension_mask extention(s) define the extension mask used by the the file parser
--movie_api imdb or tmdb set movie api provider
--movie_destination path set movie relocation destination
--movie_template template set movie renaming template
--television_api tvdb set television api provider
--television_destination path set television relocation destination
--television_template template set television renaming template


Whereas options configure how mnamer works, directives are one-off parameters that are used to perform secondary tasks like exporting the current option set to a file.

Option Arguments Description
--config_load path import configuration from file
--config_save path save configuration to file
--id id explicitly specify movie or series id
--media movie or television override media detection
--test_run mocks the renaming and moving of files

Configuration Files

In addition to the option argument flags listed above, mnamer can also be configured via JSON configuration file(s). These are loaded and applied from the following locations, in the following order:

  1. As .mnamer.json within the current working directory (e.g. ./.mnamer.json)
  2. As mnamer.json from within the user config directory (e.g. ~/.config/mnamer.json)
  3. As .mnamer.json from the user home directory (e.g. ~/.mnamer.json)
  4. Any path explicitly passed using the --load_config directive


You have complete control of how media files are renamed using mnamer's template options:

  • you can use templating with the following options: television_destination, television_template, movie_destination, movie_template
  • metadata fields prefixed with a sigil $ found inside angle brackets with the result of a match
  • any leading or trailing whitespace will be trimmed
  • if a field can't be matched, the entire contents of the bracket are disregared

Example: SxE Episodes Format

  • television_template: <$series - >< - $seasonx><$episode - >< - $title><$extension>
  • target: ~/Downloads/Rick.and.Morty.S02E01.WEBRip.x264-RARBG.mp4
  • result: ~/Downloads/Rick and Morty - 02x01 - A Rickle in Time.mp4

Example: Missing Metadata

Note: Target file is missing group metadata field in title and will be omitted gracefully

  • television_template: <$series - >< - S$season><E$episode - >< - $group - >< - $title><$extension>
  • target: ~/Downloads/The.Orville.S01E01.1080p.WEB-DL.DD5.1.H264-RARBG.mkv
  • result: ~/Downloads/The Orville - S01E01 - Old Wounds.mkv

Example: Subdirectories

Note: If the subdirectory doesn't exist, mnamer will create it

  • movie_template: <$title ><($year)><$extension>
  • movie_destination: /media/movies/<$title ><($year)>
  • target: ~/Downloads/The.Goonies.1985.720p.BluRay.x264-SiNNERS.mkv
  • result: /media/movies/The Goonies (1985)/The Goonies (1985).mkv

Metadata Fields

Field Description
title movie or episode title
year movie release year
series tv series' name
season tv series' airing season number
episode tv series' airing episode number

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for mnamer, version 1.4.2
Filename, size File type Python version Upload date Hashes
Filename, size mnamer-1.4.2-py2.py3-none-any.whl (11.6 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size mnamer-1.4.2.tar.gz (12.7 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page