Documentation

Everything you need to get started with Movie Renamer Ultimate.

Getting Started

Movie Renamer Ultimate is a desktop application that automatically renames your movie files and folders using metadata from The Movie Database (TMDB). It's designed for users of media servers like Kodi, Plex, and Jellyfin who need their files in a specific naming format.

The app parses your filenames, searches TMDB for the correct movie information, and renames the files to a clean Movie Name (Year) format.

Installation

Option 1: Download the Installer

Purchase the installer ($19.99) and download the .exe (Windows) or .dmg (Mac). Run the installer and follow the prompts - no Python required.

Option 2: Build from Source

git clone https://github.com/joshlehman/movie-renamer-ultimate.git
cd movie-renamer-ultimate
pip install -r requirements.txt
python movie_renamer_complete.py

Requires Python 3.x with pip installed.

TMDB API Key Setup

You need a free TMDB API key to use Movie Renamer Ultimate. Here's how to get one:

  1. Go to themoviedb.org/signup and create a free account
  2. After logging in, go to Settings → API
  3. Click "Create" and select "Developer" for the API key type
  4. Fill out the application form (you can use any URL for the website)
  5. Copy your API Key (v3 auth)
  6. In Movie Renamer Ultimate, go to Settings and paste your API key

Usage Guide

Renaming Files

  1. Open Movie Renamer Ultimate
  2. Drag and drop movie files or folders into the app, or use the "Add Files" button
  3. The app will parse filenames and search TMDB for matches
  4. Review the proposed renames in the preview panel
  5. Click "Apply" to rename all files

Output Format

Files are renamed to the Kodi/Plex/Jellyfin compatible format:

Movies/
  Blade Runner 2049 (2017)/
    Blade Runner 2049 (2017).mkv
  The Dark Knight (2008)/
    The Dark Knight (2008).mp4
  Inception (2010)/
    Inception (2010).mkv

Supported Filename Patterns

The app handles a wide variety of filename formats:

# Quality tags (stripped automatically)
Movie.Name.2020.1080p.BluRay.x264-GROUP.mkv
Movie.Name.2020.2160p.WEB-DL.DDP5.1.H.265.mkv

# Roman numerals (handled correctly)
Rocky.IV.1985.720p.mkv  →  Rocky IV (1985)
Blade.II.2002.1080p.mkv  →  Blade II (2002)

# Release group tags (removed)
Movie.Name.2019-RARBG.mp4
Movie.Name.2019.[YTS.MX].mkv

Media Server Integration

Kodi

After renaming, Kodi will automatically pick up the new file structure during its next library scan. You can also trigger a manual library update from Kodi's settings.

Plex

Plex uses the Movie Name (Year) format natively. After renaming, scan your library in Plex to pick up the changes.

Jellyfin

Jellyfin follows the same naming conventions as Plex. Run a library scan after renaming to update your library.

Troubleshooting

TMDB API key not working

Make sure you're using the v3 API key (not the Bearer token). Check that there are no extra spaces when pasting.

Movie not found on TMDB

The app tries multiple search strategies including title-only and partial matches. If a movie still isn't found, try renaming the file closer to the actual movie title before processing.

Permission denied when renaming

Make sure you have write permissions to the folder containing your movie files. On Windows, try running the app as administrator. The app will fall back to copy operations if direct rename fails.

Wrong movie matched

If the year is missing from the filename, the app may match the wrong version of a movie. Include the year in the filename for best results.