Fylm is a wonderful automated command line app for organizing your film media. You can pronounce it Film or File 'em, whichever you like!

It uses (highly suspect) heuristics to identify film files (or folders), then looks them up on TMDb to get all the correct details. Once that's over and done with, it'll rename them according to your OCD standards, and move them.


Fylm can:

  • Rename messy files and folders and make them pretty, like

    high.noon.1952.1080p.this.OTHER-JUNK ยป High Noon (1952) 1080p

  • Look film details up on TMDb so you don't have to, ensuring things are named correctly.

  • Check your library for duplicates and allow films with different qualities to be upgraded or ignored.

  • Notify your Plex Media Server when it adds something new.

  • Be wired up as a post-script for apps like SABnzbd (you'll want to use the --plaintext switch).

  • Delete extra files you don't want, moving only the important bits you care about.

  • Run in test mode so you can verify search results before committing.

  • Log what it does, so if (not saying they will, but if) things go sideways, you can see why.

  • Send you informative notifications to your phone when it does things.


Fylm is tested on 3.6, 3.7, and 3.8 and will attempt to adapt as the Python language does.
As of Python 2.7 end of life, 2.X is no longer supported. v0.3.1 is the last version to support Python 3.5.

Installing dependencies is simple if you use pip. Depending on your OS configuration, you may need to install packages with sudo:

(sudo) pip install -r requirements.txt
// or
pip3 install -r requirements.txt

If you don't use pip, then you will need to install these manually, or download them and include them inside your copy of Fylm. Or shake a magic stick and hope it works (hint: it won't).


All of Fylm's options are configured in config.yaml. Options of note that you should set up:

  • source_dirs
  • destination_dir
  • rename_pattern
  • tmdb.key
  • plex.baseurl
  • plex.token
  • plex.sections
  • pushover

If you're using Pushover, you might also want to add the Fylm logo to your app.


If you don't want or need anything special, simply:

python fylm

from the root project folder will run the app.

However, since we're putting a lot of faith in machines and automation, there are times when you should walk before you run, and look before you leap. For that, there are several great command line options available to you. Most of these can be configured in config.yaml, but using the command line option will override whatever is in config:

--quiet, -q
--test, -t
--debug, -d
--rename, -r
--copy, -c
--move, -m
--interactive, -i
--limit=n, -l
--pop=n, -p
--force-lookup, -f
--no-duplicates, -d
--overwrite, -o
--source, -s
  • quiet will suppress notifications or updates to services like Plex.
  • test will run the app in sandbox mode, which means no changes will actually be performed on the filesystem. A good rule of thumb is to always test first before you run the app on a long list of files.
  • debug will run the app with some extra details (ok, verbose word porridge) in the console.
  • rename will just rename files and folders and leave them in the source folder.
  • copy will force files on the same partition to be copied and verified instead of moved.
  • move will force the behavior of move even if source and destination are on different partitions.
  • hide-bad will hide files and folders that are marked as bad from the console output. Disabled in interactive mode.
  • interactive prompt to confirm or correct TMDb matches.
  • limit=n limits the number of films to process to n.
  • pop=n will set the minimum acceptable TMDb 'popularity' ranking to n.
  • force-lookup will look everything in your source folder(s) up on TMDb, even if something doesn't appear to be a film. Helpful for finding files with missing years, but can take a lot longer to run.
  • no-duplicates will disable duplicate checking entirely.
  • overwrite means that any duplicates it finds at the destination will be overwritten, even if they are smaller or lower quality. Use with caution (and run --test first!). Only YOU can prevent data loss.
  • source overrides your usual source_dir setting with new source folder(s). Comma separate multiple folders.
  • no-strict will dramatically reduce the criteria that is is used to validate TMDb matches. Expect red herrings. Lots. So, --test first.
  • no-console will completely suppress console output. If you wanted that, for some reason.
  • plaintext will output to the console without pretty formatting. You'll want to use this option with SABnzbd.

If you'd like to run this automatically with some specific options, you can create a new file (e.g., post-script.py) and do:

#!/usr/bin/env python
import subprocess
subprocess.call(["python3", "/path/to/fylm/fylm", "-s", "/Volumes/Downloads", "--plaintext"])


Tests are run using pytest. To install:

(sudo) pip install -r requirements-test.txt

To run tests:

cd fylm/
python -m pytest -xq (--no-print-logs)