Skip to main content

Bulk renaming of files made easy

Project description


docs test codecov

RenameRename is a command-line utility app that bulk renames a set of files based on some specifications. What's special about this tool, among so many other similar ones, is that it's straightforward to use.

If you don't feel like dealing with complex regex's and just want the job done without any learning effort, then hopefully RenameRename can cater to your bulk renaming needs. 😄

The main usage of RenameRename is as a CLI tool. Nevertheless, it can also be used as a package of modules containing utility classes and functions for your own modules.

Feel free to take a look at the API reference / documentation.


To run the CLI tool, you primarily need the following installed on your system:


To install the package, you can do so with pip.

pip install renamerename

Otherwise, if you want to install from source, just clone the repository in the directory of your choice, and then install it with pip, as such:

git clone
pip install -e RenameRename


In order to use RenameRename, run the Python package with:

renamerename [options]


By default, RenameRename searches for files in the current working directory. Otherwise, a different one can be set using the --dir option.

Filtering of files is done via Unix filename patterns supplied with the --filter, such as:

Pattern Usage Example
None exact characters file -> file
* any number of characters img* -> img_foo.tar.gz, img123.png, img, etc.
? any single character doc?file -> doc_file, doc1file, docsfile, etc.
[seq] any character in seq file_[abcdef].txt -> file_a.txt, file_b.txt, etc.
[!seq] any character not in seq file_[!abc].txt -> file_d.txt, file_1.txt, file__.txt, etc.

You can check which files are filtered out by providing the filter option without any actions.

renamerename --filter "img_*"
# OUTPUT: filter all files beginning with: img_


  • It is necessary to enclose filter arguments with double quotation marks " ", as this would allow you to pass the literal filter expression to the command (otherwise, the shell would process it, resolve the filenames itself, and pass invalid arguments to the command).
  • RenameRename acts on non-hidden files inside a directory. Also, the file search is non-recursive and does not take into account directory names.

Basic Actions

Some basic actions to rename filtered files are provided. The more specific the action, the better.

Action Usage Example
--prefix PREFIX prepends PREFIX to the filename file.txt -> PREFIXfile.txt
--suffix SUFFIX appends SUFFIX to the filename file.txt -> fileSUFFIX.txt
--change-extension .ext changes the file extension file.txt -> file.ext
--add-numbering PREFIX changes the filename to PREFIX and appends a counter myarchive.tar.gz, myfile.txt -> PREFIX1.tar.gz, PREFIX2.txt

You can of course use multiple actions at the same time.

For instance, if you want to add a prefix, suffix, and change the extension of files beginning with "myfile" and ending with ".png", execute the following:

renamerename --filter "myfile*.png" --prefix foo_ --suffix _bar --change-extension .jpeg
# Filtered files: myfile_a.png , myfileee.png , myfile_somechars.png
#        myfile_a.png  --->  foo_myfile_a_bar.jpeg
#        myfileee.png  --->  foo_myfileee_bar.jpeg
#        myfile_somechars.png ---> foo_myfile_somechars_bar.jpeg

Only Show Renaming Output without Execution

If you just want to see what would happen if some options and actions were supplied without actually renaming your files, you can do so by supplying the --only-output-results or -o flag. This way, you can review if the renaming will be done as intended and without any consequences.

renamerename [actions] -o

Saving What Was Renamed to What

If you want to save all the source and target filenames for future reference (in case wrong files were renamed), you can supply the --save-renaming flag to do that.

renamerename [actions] --save-renaming

This creates a JSON file in the directory supplied with --dir (or if no directory was supplied, the current directory) that contains the necessary changes.

Rename by Loading a JSON file

Renaming can also be done by supplying a JSON file that dictates the source and target filenames needed. In this case, no filtering is done, but rather the source filenames are manually entered in the JSON file.

The supplied file, via the --from-json option, should be a dictionary of source filenames mapped to target filenames. Example:

"myfile_a.png": "foo_myfile_a_bar.jpeg",
"myfileee.png": "foo_myfileee_bar.jpeg",
"myfile_somechars.png": "foo_myfile_somechars_bar.jpeg"

Suppose this file was called renaming.json, you can execute the renaming by:

renamerename --dir DIR --from-json renaming.json

Undo Renaming

In case you did not intend to execute the renaming of files, you can undo this with the --undo-from-json option, in which RenameRename will reverse the renaming.

The renaming can only be undone if in the previous call to RenameRename, you used the --save-renaming option. The JSON file created in that call needs to be supplied to the --undo-from-json option. The mapping is reversed internally.

renamerename --dir DIR --undo-from-json renaming.json

Otherwise, if you do not have the JSON file, you can create one manually and execute RenameRename with the --from-json option.


usage: renamerename [options]

Bulk renaming of files made easy.

optional arguments:
  -h, --help            show this help message and exit
  --dir directory       directory whose filenames are processed
  --only-output-results, -o
                        only show renaming results without execution
  --filter FILTER, -f FILTER
                        filter the directory contents according to Unix
  --prefix PREFIX, -p PREFIX
                        add a prefix to filtered filenames
  --suffix SUFFIX, -s SUFFIX
                        add a suffix to filtered filenames
                        change the extension of the filtered filenames
  --add-numbering ADD_NUMBERING, -n ADD_NUMBERING
                        change filtered filenames to same name suffixed with
                        increasing numbers
  --save-renaming, -sr  create JSON file containing all files renamed
  --from-json JSON file path
                        rename set of files as described from JSON file
  --undo-from-json JSON file path
                        undo renaming of set of files based on saved renaming
  --version             show program's version number and exit


The RenameRename Python package includes unit tests for developers who wish to locally test it (especially upon contributing).

For that, you first need to install the testing dependencies via:

pip install -r requirements-dev.txt

The tests can be run with pytest and executed via the following:

cd repository_root   # enter the root directory of the repository


The documentation (mostly the API reference) to the Python package currently resides on GitHub Pages.

For contributing developers, building the docs locally requires the following:

pip install -r docs/requirements-docs.txt
apt-get install make

You can then build the docs with:

cd docs   # relative to repository root
make html

Project details

Download files

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

Source Distribution

renamerename-1.0.0.tar.gz (18.5 kB view hashes)

Uploaded source

Built Distribution

renamerename-1.0.0-py3-none-any.whl (19.1 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page