User Tools

Site Tools


TV File renaming script

Here you'll find a little program which can rename your video collection for you, it has the following nifty features:

  • Automatically downloads episode titles from the web
  • Can handle a massive variety of filenames
  • Cleans up long filenames
  • Very customisable
  • Completely automatic!
Download Version
Latest Perl script
Win32 bare executable v2.57 (2020-04)
2015-01-31 Perl script updated

Note: No longer using version numbers, as project is now hosted on and only receives bug-fixes, not major new features.

  1. Remove AniDB support
  2. No longer tries to rename hidden files
  3. Fixed #15, #16, #17, and #18 on
    • #15: $shortSeries name for “Doctor Who (2005)”
    • #16: Special episode handling for EpGuides faulty
    • #17: Some Series paths on are wrong
    • #18: Unsuccessful run leaves .URL junk file behind

Found a bug? Please report it at


There are two flavours of the script, the normal Perl script which works on any computer which has the Perl scripting language installed on it, and a special Windows-only executable. If you don't know which one to download, try the Windows-only one, it won't bite.

Perl script proper

The Perl Camel Works on any platform which has the Perl scripting language installed. Perl comes pre-installed with most Linux distributions and Mac OS X, if you don't have it you can get it readily from

Download as Perl script

Windows-only binary

Limited support. This version may be out-of-date.

My last installation of Windows corrupted itself, and I've no intention of fixing it. I rely on the kindness of others to compile these binaries. Big thanks to Danny Fallon for donating the current version!

Windows Vista logo A special Windows-only version, which is created out of the Perl script proper above. It's a much bigger download, and is known to have some minor glitches, but it doesn't require you to have Perl installed.

The documentation talks about Rest assured that this version (tvrenamer.exe) works identically.


Please skim over this page to get an idea of how to use the script effectively, and email me if you have any comments / suggestions and what-not!

Getting Started

This section is a “least you need to know” approach to documentation. Once you're familiar with the basics you may want to check the advanced section to see all that you can achieve with the script!

Basic Usage

Group your videos into folders, one season per folder. Name the folder like this:



  • “Smallville 6x”
  • “Rome 1x”
  • “Southpark 10x”

Now to run the script. Move the script1) into the same folder as your videos and run it by double-clicking.

The script may take about 10-15 seconds to load, and then you should see it something like the following:

Detected series name 'Smallville' (Season 6)
Reading input in AutoFetch mode from
Fetching document ... [Done]
Generating changes...

Proposed changes:

Smallville 6x01 - Zod.avi
Smallville 6x02 - Sneeze.avi
Smallville 6x03 - Wither.avi
Smallville 6x04 - Arrow.avi
Smallville 6x05 - Reunion.avi
Smallville 6x06 - Fallout.avi
Smallville 6x07 - Rage.avi
Smallville 6x08 - Static.avi
Smallville 6x09 - Subterranean.avi
Smallville 6x10 - Hydro.avi
Smallville 6x11 - Justice.avi
Smallville 6x12 - Labyrinth.avi
Smallville 6x13 - Crimson.avi
Smallville 6x14 - Trespass.avi
Smallville 6x15 - Freak.avi
Smallville 6x16 - Promise.avi
Smallville 6x17 - Combat.avi
Smallville 6x18 - Progeny.avi
Smallville 6x19 - Nemesis.avi
Smallville 6x20 - Noir.avi
Smallville 6x21 - Prototype.avi
Smallville 6x22 - Phantom.avi

Would you like to proceed with renaming? [y/N/?]:

Press “Y” and you're done!

Helping yourself

It's always good to know how to approach a problem. When you find the script isn't doing exactly what you want, try the built-in help for a list of options: --help

Common Pitfalls

Dubious numbering

Some series, notably Southpark, number their files without a gap between the season number and the episode number. For example, “1005.avi” is season 10, episode 5. The script will read this number as episode “1005” of whatever season it thinks the folder is2). To correct this, use: --dubious

This will make the script use only the last 2 digits of a number in the file name as the episode number, using the rest as the season.

I want it to add a leading zero to the episode numbers!

The script tries to make as few assumptions as possible, which means that if the data it found on the web for your series only lists, say, 6 episodes of a 22 episode series it cannot know that the series will eventually be 22 episodes. It works on what it knows to be true and in this case that means: “There are 6 episodes”. So it considers a single-digit number to be sufficient.

If the website was updated to list the first 10 episodes, then the script would think “Ah, I'm going to need more space for the numbers” and will pad the single-digit numbers with zeros. This scales well: When I rename my 260+ episode series, it pads the numbers so they are all 3-digits long.

However, you can override this if you like. Just tell the script how many digits you want your numbers to be: --pad=2

I see loads of gibberish!

If you see a lot of nonsense, such as “←[31m”, try the --noANSI option when you run the script. This disables fancy text formatting, such as using colour etc.

“ANSI” is the colloquial term for ANSI Escape Codes, which is a way of displaying coloured text. If you have ever dabbled in HTML it's a bit like a <font> tag which is hidden from sight but magically changes the way text is displayed.

Workaround for DOS

You do not need to do this for the Windows-only build (*.exe). This is for people who use the *.pl version from a DOS prompt.

DOS doesn't natively support ANSI escape sequences, but if you install the Perl module Win32::Console::ANSI you need only comment-in a line near the top of the script to enjoy colour.

Remove the “#” infront of this line:

#use Win32::Console::ANSI;  # Hack to fix up Win32 console to support ANSI  (

Can I rename folders without having to copy tvrenamer.exe all the time?

Because I'm in a bit of a rush, here is the latest email I wrote answering this question (also, see below for an even better solution):

Of course the simplest answer is to make shortcuts instead of copying, but that doesn't really solve the problem - it's a manual step for each folder!

I got a better solution to this problem from Dave (thanks!):

..and then Adrian sent me a script he uses, which finds the directories for you! Thanks very much Adrian!

The script below is not compatible with Windows, unless you use Cygwin

How can I make my command-line options the default

This guide is intended for Windows users

You can create a preferences file, which tvrenamer.exe will read every time you run it. This file contains all the options you might want to include on a command line or in a shortcut, without the hassle of actually including them.

First you need to create an empty text file with a special name that Windows doesn't usually like (sorry, the script was originally written for Linux). Create the file like so:

 START > Run > "cmd.exe" > OK
 "echo. > .tvrenamerrc" <ENTER>
 "notepad .tvrenamerrc" <ENTER>

This should pop up notepad with an empty file. Enter text so that the file contains the commands you want to appear by default, one per line. For instance, if you didn't want it to ask you for confirmation, you could add:


and then save it. Now when you run tvrenamer.exe it should not prompt you to answer any questions, and will assume “Yes” to renaming, and “No” to any other questions (to make sure it doesn't trash your files by doing something weird).

Do not move your preferences file to another location - tvrenamer.exe only looks in your “home” directory3), which happens to be where new command-prompts start in.
Do not use quotes in your .tvrenamerrc file — this breaks the script. When .tvrenamerrc is read in, each line will have double-quotes added around it, so you don't need to!


(In order of appearance)

Sar: Seriously, thanks for making your work available; I think this has to be the third most useful software tool I've used to further my anime-watching experience, the other two being the media player and the download tool. Messily-named files wind me up something rotten. ;-)

TonyW: Thanks for this superb little script (Tv episode file renamer)!

Rolf: I found your rename script today and tried it on a couple of episodes. Simply awesome!

TonyJ: This script is absolute gold! I thought about doing a similar thing in ruby, but this works a treat!

Zhen: Keep up the good work

JesusG: Very impressed with your script!!! It's become a essential in my software favourites. Thank you very much :-)

BrockH: I like your renaming script… only downloaded it tonight, but it's worked fine on the couple of series I've run it on.

PhilS: First of all, great script! Love it. Took me a while to setup my .tvrenamerrc but it's all looking good now.

DavidA: First off, I'd like to thank you for a great script. I've been looking for something like this for a while now.

GeoffA: First just wanted to say thanks for the tv renamer script. It's something I've been wanting for a very long time but had never bothered looking for since I didn't really think anyone had written one. I actually stumbled on it completely by accident.

If you want to speak louder than words, I invite you to donate something - but please, don't feel you have to! I maintain this script because I enjoy it!

If you need help

If you are having problems, and skimming the manual and trouble-shooting doesn't help, don't hesitate to find me online (but please mention the script or I might think you're spam!) or send me an email:

Contact the author

Skype: robertmeerman
IRC: RobM, in #CompSoc and #anime on
ICQ: 37099562 (Page me4))


I want the manual to explain all aspects of the script in an accessible manner. In practice this means I intend to document the effects of all options available to the script, with lots of examples.


This script started back in late 2001 as a one-line Perl command that removed the word “Chapter” from every file in the current directory. Back then I didn't know any Shell-scripting or Perl, so that was my first Perl script ever!

Perl and it's regular expressions intrigued me, so I spent some time reading the Linux man pages and eventually set myself the challenge of making a script that could rename every file in a folder using a list of desired filenames.

It's been evolving ever since, and now sports some rather nifty features!

System Requirements

If you are using the Perl script proper ( you need to have Perl installed, and have the following modules available (all available through CPAN):

  • Switch
  • Term::ReadKey
  • Cwd
  • LWP::Simple3
  • URI::Escape
  • Compress::Zlib
  • File::Glob
  • (Windows users only) Win32API::File
  • (Windows users only) Encode

If you are using the Windows-only build, then you only need Windows.


This script takes episode title data as input and tries to match it to the files present in the current directory. For this to work properly both the episode data you feed it, and the filenames need to be in a format that the script can understand.

Feeding the script data

There are multiple ways of feeding the script episode titles you want applied to the file in the current folder:

  1. Copy and Paste the data from a website to the script
  2. Copy and paste the data from a website into a textfile for the script to use
  3. Instruct the script which webpage to download and use
  4. Let the script search the web automatically

Normally you will want to use the last method, as it is the most convenient and works in most cases. Below I will explain how to use the various methods with any tips that come to mind, as well as some examples.

Copy'n'Paste to the script

This was the first mechanism the script had for getting data. It may still be useful in modern versions because it is less susceptible to cosmetic changes in a website than some of the modern parsers.

Invoke this mechanism by passing the “-” option to the script: -

You should see something like the below:

Detected series name 'Smallville' (Season 6)
Reading input in AutoDetect mode from STDIN (Press ^D to end):

Now you goto one of the supported websites (see --help for a list) and copy the episode data to the clipboard, then paste it into the terminal you are running the script in. Press return a couple of times to make sure you're on a new blank line, and then press CTRL + D to signal you're done pasting text.

For example, I would paste the following data from

111.   6- 1     2T7701     28 Sep 06   Zod
112.   6- 2     2T7702      5 Oct 06   Sneeze
113.   6- 3     2T7703     12 Oct 06   Wither
114.   6- 4     2T7704     19 Oct 06   Arrow

The script ought to then suggest the following:

Proposed changes:

Smallville 6x01 - Zod.avi
Smallville 6x02 - Sneeze.avi
Smallville 6x03 - Wither.avi
Smallville 6x04 - Arrow.avi

Copy'n'Paste to a text-file

This mechanism is useful for off-line renaming because the script does not need to contact a website to obtain the episode titles.

Same as the previous section, except you save the episode title data into a text-file which you must place in the same directory as your videos, and name specially using the website lists in --help. For instance, the built-in help contains the following line:

  --EpGuides         Assume input is in format

So you would name the text-file EpGuides.txt, although the case is not important. To use this text file you would simply run the script in the current directory, and it will pick it up.

FIXME: It shouldn't be necessary to give the text-file a special name.

Provide the script with an URL

This is perhaps the second most useful mechanism, it's handy for when the script is having a retarded moment and cannot work out what your series is called.

Find the page on one of the supported websites (see the list in --help) which lists all the episode titles, and provide this link to the script on the command line. Be sure to include the quote marks on Linux and Mac OS X! 5) ""
The script also picks up URL shortcuts in the current directory. So you could create a shortcut to the webpage you want the script to use. (Supports both Windows .URL and Linux/Mac OS X .desktop shortcuts)

Let the script search the web

By far the most convenient mechanism, when it works. I'm always looking to add support for more websites, so let me know if the script isn't compatible with your favourite site!

As this is the default behaviour, you do not need any arguments to the script:
The script attempts to discern whether your series is Anime or not (and uses different websites for each) by looking for a folder called “anime” among the to-be-renamed's parent folders.

Hence /media/anime/Complete/One Piece is an anime, and /media/Complete/One Piece is not. See the --search option.

For this mechanism to work you need to make sure the script has the “correct” name of the series in mind when searching. “Correct” here means that it matches what the website says. For example the recent Dr Who series is called “Doctor Who 2005”, even though I prefer to think of it as “Dr Who 27x”.

Either rename the folder to match the website, or amend the script's behaviour using some of the advanced options which are described later. For completeness here is how I tackled the above Dr Who problem: I kept my folder called “Dr Who 27x” and used the following command: --series=DoctorWho_2005 --season=1 --postproc='s/DoctorWho_2005/Dr Who/;s/ 1x/ 27x/'

How does this work?

  • The --series= switch overrides the name which is normally taken from the folder's name.
  • The --season= switch again overrides the season which is normally taken from the folder's name.
  • The --postproc= switch is a highly advanced one which allows me to inject some Perl script for this run only. I've specified two substitutions:
    1. s/DoctorWho_2005/Dr Who/ which replaces the first occurrence of “DoctorWho_2005” in the new filename with “Dr Who”.
    2. The second substitution is s/ 1x/ 27x/ which replaces the first occurrence of “ 1x” in the new filename with “ 27x”.

Without the --postproc- the script would suggest new filenames like this:

DoctorWho_2005 1x01 - Rose.avi
DoctorWho_2005 1x02 - The End of the World.avi

With the --postproc= I get this:

Dr Who 27x01 - Rose.avi
Dr Who 27x02 - The End of the World.avi
I plan to rewrite this soon


As I wrote the script, it pretty much always works for me. So I need your help making this bit useful, if you have a problem getting to run please email me, even if you don't much care about making it work and will never return to my site! If you encountered a weird problem and managed to fix it yourself, please also let me know so others can benefit from your solution!

To report a problem, email, including a problem description and output log (or screenshot if you don't know how to log output).

In the meantime, here are somethings to check:

Perl requirements (n/a for Windows executable)

Do you have all of the following Perl modules installed?

  • Switch
  • Term::ReadKey
  • Cwd
  • LWP::Simple3
  • URI::Escape
  • Compress::Zlib
  • File::Glob
  • Text::Unaccent
  • (Windows users only) Win32API::File
  • (Windows users only) Encode

You can install these modules using the cpan command. You can think of it as a Perl package manager. Run the following command from a command-prompt:

All platforms:

cpan Switch Term::ReadKey Cwd LWP URI::Escape Compress::Zlib File::Glob Text::Unaccent

Additional command for Windows (these are needed to work around Unicode issues)6):

cpan Win32API::File Encode


You may need to convert the file from DOS line-endings to Unix ones. Popular utilities for this are “fromdos” and “dos2unix”.


  • AutoFetch mode that automatically searches, & for your series
    • Automatic detection of anime series, though can be manually specified with --series=anime or explicitly avoided with --series=tv.
  • AutoDetect support for multiple copy'n'paste formats
  • AutoDetect support for some fetched webpage formarts
    • (for anime)
    • “All Seasons” episode list format (very useful)
  • Ability to read any of the above from appropriately named text files, such as “AniDB.txt” or “TV.txt”.7)
  • Changes are reversible via ''–interactive'' switch which creates or updates a “” (or “unrename.bat” if you use the EXE version of the script)
  • Option to select changes interactively (''--interactive'')
  • Uses current directory name as series name, allowing you to conveniently change series names at any time. An example use might be to distinguish season 1 from a recently-started season 2.
    • Directory structures such as “House/Series 1/*” are interpreted as you would expect: SeriesName=“House”, Season=1
    • Recognises the following parts of the current directory's name.
      • “ (Complete)” at the end is ignored, as it is assumed to be a user note
      • “ (onDisc)” at the end is ignored, as it is assumed to be a user note
      • “Series Name 1x”, “Series Name 2x” is recognised as “Series Name” seasons 1 and 2 respectively, and file names will have “1x” and “2x” placed before their episode number appropriately — i.e. 1×01, 1×02, 1×03… and 2×01, 2×02, 2×03… (different numbering schemes can be chosed with the --scheme= option detailed below)
    • Series name can be manually specified with a command-line switch (--series=X)
    • Series name can be obtained from fetched webpages (--autoseries)
    • Season number can be manually specified with a command-line switch (--season=X)
  • Group-tags can be stripped completely if not desired (--nogroup)
  • Gap character can be specified (i.e. instead of “House 2×01 - Acceptance.mkv”, you get “House.2×01 - Acceptance.mkv” which is more script-friendly as the header no long contains spaces).
  • Handles episodes “specials”
    • Anime: Does seperate renaming for 'S'-type specials on, naming them (S01, S02, S03..)
    • Auto-Ranges input, discarding everything after large gaps by default (can be overridden with --noautoranging) — this takes care of “specials” on
  • Multiple season/episode number formats in file names are recognised (EG season 1, episode 8):
    • “Season 01 Episode 08”
    • “s01.e08”
    • “s01e08”
    • “1×08”
    • “S08”
    • “08”
    • “108” (you use the --dubious command-line argument to detect this as 1×08, instead of 1×108)
  • Various numbering schemes for new file names (more can be very easily added):
    • “s01e08”
    • “1×08”
    • “08”
    • Default behaviour is “1×08” when the season number is explict, and “08” otherwise.
  • Double-episodes of all variants above, such as “1×08-09”
  • Dubious number extractor emmits warning when a file's episode number “108” is assumed to be season 1, episode 08, instead of episode 108 of whatever series the script thinks it's looking at (typically “1” unless told otherwise)
  • Episode numbers are padded so they are all the same number of digits. For instance “1” → “01” if the input has 10 or more eps
  • “Unixy” mode, for those that prefer underscores (“_”) to be used instead of spaces in file names (--unixy)
  • “Clean up” mode, which does not require input and simply discards CRC32 checksums (such as “[037AF5A]”) from filenames, moves group tags to the end, and swaps underscores for spaces (or vice versa if “Unixy” mode is enabled) (--cleanup)
  • Supports ANSI colour, allowing a prettier interface if your terminal supports it (--ANSI). If you see gibberish on your screen, disable this with --noANSI!
  • Pre/Post Processor which evalutates PERL which has been given on the command line before/after internal filename processing. (For experts only, and silently ignored by the .EXE version)
  • Ability to cache downloaded webpages (--cache), which creates a .cache file — this is useful if you want to experiment with different settings, or are debugging / altering the script.
  • Unattended mode for batch processing and scripting
  • Interactive mode to select changes on a file-by-file basis for those tricky situations

Script assumptions

The script makes a few assumptions about your setup:

  • All files to be renamed in the current directory are from the same series (there is limited support for files from different seasons of the same series being in the same directory, but only if the file names are distinctive enough to allow this)
  • All filenames contain their episode number (in any notation supported, EG: 08, 1×08, s01e08…)

It also makes a few assumptions in an attempt to be helpful (these can be overridden):

  • If a file called AniDB.txt is in the current directory, it uses it as input, reading it as AniDB data.
  • If a file called TVtorrents.txt is in the current directory, it uses it as input, reading it as TVtorrents data.
  • If a file called TVtome.txt is in the current directory, it uses it as input, reading it as TVtome data.
  • If a file called TV.txt is in the current directory, it uses it as input, reading it as data.
  • If a file called TV2.txt is in the current directory, it uses it as input, reading it as “All Seasons” data.
  • If a file called EpGuides.txt is in the current directory, it uses it as input, reading it as EpGuides data.
  • If a .URL or .desktop file exists, it is read and checked for an URL (http://...), if found this is fetched and used as input
  • If you none of the above apply, and you didn't specifically tell it otherwise, you would like it to search and then for you.
  • The current directory's name is also the series' name.
  • You only want to rename files which end in one of: avi|mkv|ogm|mpg|mpeg|rm|wmv|mp4


You can subscribe to this page to be notified of changes, such as the release of new versions.

See the Subscribe Changes button at the bottom of this page.

The script is either called or tvrenamer.exe depending on which version you downloaded
Remember that the script uses the folder's name to work out the season, so “Southpark 10x” would mean the folder is season 10
Typically something like C:\Documents and Settings\username
This show you a webform where you can just tap your name and a message and hit “Send” and I'll get it, can be more convenient than email sometimes…
If you don't an ampersand (&) may background half of your command and cause the other half to produce an error…
Windows uses UTF-16LE encoding for Unicode, and Perl doesn't seem to support this out-of-the-box. Therefore we need to use the Win32API's directly to get the raw data of filenames, and then use the Encode module to convert this to match Perl's internal Unicode encoding.
Names are dictated by the command-line switch needed to use that format, plus “.txt” on the end, try “rename --help” to obtain a list of available switches
coding/file_renamer.txt · Last modified: 2020/04/27 17:56 by robm