4.0.0 • Public • Published

    view on npm npm module downloads Gihub repo dependents Gihub package dependents Build Status Coverage Status js-standard-style

    Upgraders, please read the release notes. Please share feedback and improvement ideas here.


    Renamer is a command-line utility to help rename files and folders. It is flexible and extensible via plugins.


    Always run this tool with the --dry-run option until you are confident the results look correct.


    The examples below use double quotes to suit Windows users. MacOS & Linux users should use single quotes.

    As input, renamer takes a list of filenames or glob patterns plus some options describing how you would like the files to be renamed.

    $ renamer [options] [file...]

    This trivial example will replace the text jpeg with jpg in all file and directory names in the current directory.

    $ renamer --find jpeg --replace jpg *

    As above but operates on all files and folders recursively.

    $ renamer --find jpeg --replace jpg "**"

    Fine-tune which files to process

    If no filenames or patterns are specified, renamer will look for a newline-separated list of filenames on standard input. This approach is useful for crafting a specific input list using tools like find. This example operates on files modified less than 20 minutes ago.

    $ find . -mtime -20m | renamer --find jpeg --replace jpg

    Same again but with a hand-rolled input of filenames and glob patterns. Create an input text file, e.g. files.txt:


    Then pipe it into renamer.

    $ cat files.txt | renamer --find jpeg --replace jpg

    Rename using regular expressions

    Simple example using a regular expression literal. The case-insensitive pattern /one/i matches the input file ONE.jpg, renaming it to two.jpg.

    $ renamer --find "/one/i" --replace "two" ONE.jpg

    Rename using JavaScript

    For more complex renames, or if you just prefer using code, you can write a replace function. Create a module exporting a class which defines a replace method. This trivial example appends the text [DONE] to each file name.

    import path from 'path'
    class Suffix {
      replace (filePath) {
        const file = path.parse(filePath)
        const newName = + ' [DONE]' + file.ext
        return path.join(file.dir, newName)
    export default Suffix

    Save the above as suffix.js then process all files in the current directory using the above plugin as the replace chain.

    $ renamer --dry-run --chain suffix.js *
    Dry run
    ✔︎ pic1.jpg → pic1 [DONE].jpg
    ✔︎ pic2.jpg → pic2 [DONE].jpg
    Rename complete: 2 of 6 files renamed.


    The following gif demonstrates the default view (with and without --verbose mode), the built-in alternative views (long, diff and one-line) and a custom view.

    Further reading

    Please see the wiki for

    For more information on Regular Expressions, see this useful guide.


    First, ensure Node.js v14 or above is installed.

    To install renamer globally as a part of your regular command-line tool kit:

    $ npm install --global renamer

    To install renamer as a development dependency of your project:

    $ npm install --save-dev renamer

    © 2012-21 Lloyd Brookes <>.

    Tested by test-runner.


    npm i renamer

    DownloadsWeekly Downloads






    Unpacked Size

    32 kB

    Total Files


    Last publish


    • 75lb