Skip to main content

rename-clean - Replace Undesirable Characters in Linux File Names

PyPi

The rename-clean command line utility replaces undesirable characters with underscores in Linux file names. Undesirable characters are any that are not ASCII alphanumeric (0-9, a-z, A-Z), underscore (_), hyphen (-), or dot (.). If characters are replaced by underscores, then repeated underscores are also reduced to a single underscore and trimmed from the name stem and suffix for files, or from the name for directories. A unique name is always created by appending a number on the name stem if necessary.

An example of where I use it is after downloading an archive of files from the internet such as a torrent to remove spaces, emojis, and other odd characters from the file names.

Example usage follows:

Clean up all file and directory names in the current directory:

$ rename-clean

Clean up all file and directory names in the current directory and recursively under any child directories:

$ rename-clean -r

Clean up all jpeg file names in current directory:

$ rename-clean *.jpg

Read a list of names to be cleaned up from a file:

$ rename-clean - <list-of-bad-file-names.txt

Clean up all file and directory names, but also allow + and % characters in names. Note you can allow extra characters by default using the -a/--add option as described in the Command Default Options section below:

$ rename-clean -a='+%'

You can run with the -d/--dryrun option to see what would be changed without actually renaming anything.

The latest version and documentation is available at https://github.com/bulletmark/rename-clean.

Command Default Options

You can add default options to a personal configuration file ~/.config/rename-clean-flags.conf. If that file exists then each line of options will be concatenated and automatically prepended to your rename-clean command line arguments. Comments in the file (i.e. starting with a #) are ignored. Type rename-clean -h to see all supported options.

Installation or Upgrade

Python 3.9 or later is required. Note rename-clean is on PyPI so the easiest way to install it is to use uv tool.

$ uv tool install rename-clean

To upgrade:

$ uv tool upgrade rename-clean

To uninstall:

$ uv tool uninstall rename-clean

Alternatively, run it immediately using uvx without explicit installation by typing uvx rename-clean.

Command Line Options

Type rename-clean -h to view the usage summary:

usage: rename-clean [-h] [-r] [-d] [-q] [-i] [-m] [-s] [-c CHARACTER] [-a ADD]
                    [path ...]

Utility to replace undesirable characters with underscores in Linux file
names. Undesirable characters are any that are not ASCII alphanumeric (`0-9`,
`a-z`, `A-Z`), underscore (`_`), hyphen (`-`), or dot (`.`). If characters are
replaced by underscores, then repeated underscores are also reduced to a
single underscore and trimmed from the file name stem and suffix, or from the
directory name. A unique name is always created by appending a number on the
name stem if necessary.

positional arguments:
  path                  one or more file or directory names to rename, or "-"
                        to read names from stdin. Default is all files in
                        current directory if no path given.

options:
  -h, --help            show this help message and exit
  -r, --recurse         recurse through all sub directories (not including
                        symlinks)
  -d, --dryrun          do not rename, just show what would be done
  -q, --quiet           do not report changes
  -i, --ignore-hidden   ignore hidden files and directories (those starting
                        with ".")
  -m, --more-aggressive
                        replace repeated underscores even if there are no
                        other replacements
  -s, --symlinks-remove
                        remove symlinks instead of renaming them, to avoid
                        potentially leaving broken links
  -c, --character CHARACTER
                        character to replace undesirable characters with,
                        default = "_"
  -a, --add ADD         additional characters to allow in names, e.g. "-a=+%"
                        (default: only alphanumeric, "_", "-", and ".")

Note you can set default starting options in ~/.config/rename-clean-
flags.conf.

License

Copyright (C) 2025 Mark Blakeney. This program is distributed under the terms of the GNU General Public License. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License at https://en.wikipedia.org/wiki/GNU_General_Public_License for more details.

Metadata

Release files for rename-clean 1.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rename-clean 1.6
File Size Uploaded Provenance Actions
rename_clean-1.6.tar.gz 6.4 kB Without provenance Details for rename_clean-1.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rename-clean 1.6
File Interpreter ABI Platform Actions
rename_clean-1.6-py3-none-any.whl Python 3 none any Details for rename_clean-1.6-py3-none-any.whl

Total release size: 12.6 kB

Release files / rename_clean-1.6.tar.gz

Download URL rename_clean-1.6.tar.gz
Size 6.4 kB
Tags Source
SHA-256 checksum
How to use checksums
cbc802bfc83e9ade86648ab7b281e44d538a530e3b1c92e81febd7cf61a9537f
BLAKE2b-256 checksum
How to use checksums
207d8141a27df49aba4575046dfa9d6cb141c03e9dd43ec33167c81f27458849
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Arch Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / rename_clean-1.6-py3-none-any.whl

Download URL rename_clean-1.6-py3-none-any.whl
Size 6.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c3ad7417695dabd015c6c0055cec81c660ec28517c76753b46e38519e947ea98
BLAKE2b-256 checksum
How to use checksums
bcb59c36382677faba9978d78d0c9263c6c5bd15d75ae8a8bdb32bd433fcdff8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Arch Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for rename-clean 1.6

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page