rename-clean - Replace Undesirable Characters in Linux File Names
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.