regex-rename
Bulk rename tool based on regular expressions to rename multiple files at once.
Quickstart
Renaming multiple files at once:
$ ls # awful names:
b45XDS-01.mp3 QsEW2s-02.mp3 VF7t6L-03.mp3
$ regex-rename '-(\d+).mp3' '\1_NeverGonnaGiveYouUp.mp3' --rename
[2022-04-09 09:19:15] DEBUG matching regular expression pattern to files: pattern=-(\d+).mp3 replacement=\1_NeverGonnaGiveYouUp.mp3 full_match=False dry_run=False
[2022-04-09 09:19:15] INFO renaming file: from=b45XDS-01.mp3 to=01_NeverGonnaGiveYouUp.mp3
[2022-04-09 09:19:15] INFO renaming file: from=QsEW2s-02.mp3 to=02_NeverGonnaGiveYouUp.mp3
[2022-04-09 09:19:15] INFO renaming file: from=VF7t6L-03.mp3 to=03_NeverGonnaGiveYouUp.mp3
[2022-04-09 09:19:15] INFO files renamed: renamed=3 mismatched=0
$ ls # now we're talking:
01_NeverGonnaGiveYouUp.mp3 02_NeverGonnaGiveYouUp.mp3 03_NeverGonnaGiveYouUp.mp3
Installation
pip3 install regex-rename
It requires Python 3.7 (or newer) with pip.
Tutorial
Imagine you have 51 audio files with hideous names like this and you wish to rename them:
Stanislaw+Lem+Invincible+(01).mp3->01 The Invincible.mp3Stanis▯aw+Lem+Invincible+(02 ).mp3->02 The Invincible.mp3Stanisław_Lem_Invincible (03) .mp3->03 The Invincible.mp3- …
Stanis▯aw+Lem+Invincible+(51).mp3->51 The Invincible.mp3
Specifically, you want to place the episode number at the beginning.
Step 1: Match
Regular Expressions can be tricky. We figured out this pattern may match the files and extracts the episode number:
(\d+).*mp3
First, let's check this pattern in a dry run: regex-rename '(\d+).*mp3'
Pay attention to the extracted regex groups.
Step 2: Replace
Now, we'd like to replace all files to a pattern:
\1 The Invincible.mp3
\1 is a first group extracted by the matching pattern (episode number).
Let's test it by adding the replacement pattern: regex-rename '(\d+).*mp3' '\1 The Invincible.mp3'
Step 3: Execute
All above commands were just dry-run so that we could experiment with regex patterns.
Once we're sure that everything is matched correctly, we can append --rename flag,
which does the actual renaming:
regex-rename '(\d+).*mp3' '\1 The Invincible.mp3' --rename
Finally, files are named properly:
01 The Invincible.mp302 The Invincible.mp303 The Invincible.mp3- …
51 The Invincible.mp3
Beyond the Regex
regex-rename also supports some transformations not covered by regular expressions standard:
- Converting to lowercase by adding
\Lbefore group number:
regex-rename '([A-Z]+).mp3' '\L\1.mp3'
eg.AUDIO.mp3toaudio.mp3 - Converting to uppercase by adding
\Ubefore group number:
regex-rename '([a-z]+).mp3' '\U\1.mp3'
eg.audio.mp3toAUDIO.mp3 - Padding numbers with leading zeros by adding
\P2,\P3, … (depending on padding length) before group number:
regex-rename '(\d+).mp3' '\P2\1.mp3'
eg.1.mp3to01.mp3 - Padding numbers with leading zeros by specifying
--pad-toparameter:
regex-rename '(\d+).mp3' '\1.mp3' --pad-to=2
eg.1.mp3to01.mp3
More examples
-
Extract season and episode numbers, eg.
episode-02x05.mkvtoS02E05.mkv:regex-rename '(\d+)x(\d+)' 'S\1E\2.mkv' --rename
-
Swap artist with title, eg.
Echoes - Pink Floyd.mp3toPink Floyd - Echoes.mp3:regex-rename '([^-]+) - ([^-]+)\.mp3' '\2 - \1.mp3' --rename
-
Pad leading zeros, eg.
1.mp3to001.mp3:regex-rename '(\d+).mp3' '\P3\1.mp3' --rename
-
Convert to lowercase, eg.
SONG.MP3tosong.mp3:regex-rename '(.+)' '\L\1' --rename
-
Convert to uppercase, eg.
Tool.mp3toTOOL.mp3:regex-rename '(.+)\.mp3' '\U\1.mp3' --rename
-
Add prefix, eg.
Doors.mp3toThe Doors.mp3:regex-rename '(.+)' 'The \1' --full --rename
-
Change extension, eg.
Songbook.apktoSongbook.zip:regex-rename '(.+)\.apk' '\1.zip' --rename
-
Turn directories into prefixes and move files, eg.
Pink Floyd/Echoes.mp3toPink Floyd - Echoes.mp3:regex-rename '(.+)/(.+).mp3' '\1 - \2.mp3' --full --recursive --rename
-
Rename files in different directories, preserving their parent directories, eg.
app/logs/file-001.logtoapp/logs/file_001.txt:regex-rename '(.*)/file-([0-9]+).log' '\1/file_\2.txt' --full --recursive --rename
-
Rename files piped from another command like
find, eg.songs/Jimmi - Voodoo Child.mp3tosongs/Jimi - Voodoo Child.mp3:find -iname '*jimmi*' | regex-rename '(.*)/.* - (.*).mp3$' '\1/Jimi - \2.mp3' --rename
Usage
Enter regex-rename for help:
$ regex-rename
regex-rename v1.3.0 - Bulk rename tool based on regular expressions to rename multiple files at once
Usage:
regex-rename [OPTIONS] PATTERN [REPLACEMENT]
Arguments:
PATTERN - Regex pattern to match filenames
[REPLACEMENT] - Replacement regex pattern for renamed files. Use \1, \2 syntax to make use of matched groups
Options:
--version - Print version information and exit
-h, --help [SUBCOMMANDS...] - Display this help and exit
-r, --rename - Does actual renaming files instead of just testing replacement pattern
--full - Enforces matching full filename against pattern
--recursive - Search directories recursively
--collate - Compare source filenames with the replaced names
--short - Print output in short, less verbose format without time
--pad-to PAD_TO - Applies padding with zeros with given length on matched numerical groups
Metadata
Release files for regex-rename 1.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| regex-rename-1.3.3.tar.gz | 11.0 kB | Without provenance | Details for regex-rename-1.3.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| regex_rename-1.3.3-py3-none-any.whl | Python 3 | none | any | Details for regex_rename-1.3.3-py3-none-any.whl |
Total release size: 21.5 kB
Release files / regex-rename-1.3.3.tar.gz
| Download URL | regex-rename-1.3.3.tar.gz |
|---|---|
| Size | 11.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5f3e14d7a737f75e0b7478ecf6679745105d260a2aa2a486b6d9141cf33569d3
|
|
BLAKE2b-256 checksum How to use checksums |
4fd24acb2f161e2019b620008e364cf0bc8e079c27244e625b7ef440bae56bff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.11.6
|
Release files / regex_rename-1.3.3-py3-none-any.whl
| Download URL | regex_rename-1.3.3-py3-none-any.whl |
|---|---|
| Size | 10.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fdb862ac2b783a59faf9ec5b32307c8f75150dab3741710c6952ad0c886f1dab
|
|
BLAKE2b-256 checksum How to use checksums |
9f2bef76f6c99630c05ae193c7ac83bc1fe440f68719074d7b1e9a60537580a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.11.6
|
Security for regex-rename 1.3.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.