sanitize-filename

What it is and what it does

sanitize-filename is a lightweight, dependency-free library that cleans filenames by removing or replacing characters that are problematic for filesystems. It uses a blacklist strategy—filtering out forbidden characters rather than allowing only safe ones—which means it preserves the original filename and non-ASCII characters as much as possible. This makes it useful when you want to keep user-supplied or original filenames intact while still avoiding filesystem errors.

The package handles common gotchas like reserved names (NUL, CON, etc.), leading/trailing dots, and path separators. However, the documentation explicitly warns that blacklist-based sanitization is inherently less safe than whitelist approaches; the authors recommend creating safe filenames yourself or using a whitelist strategy when security is paramount. This package is best suited for cases where preserving the original filename is a priority and you accept the trade-off in safety.

Use it for:

• Sanitize user-uploaded filenames in web applications before storing them to disk.
• Clean filenames from external data sources or APIs while retaining non-ASCII characters for international names.
• Prepare filenames for cross-platform file operations without forcing ASCII-only names.
• Handle reserved filesystem names (like NUL or CON on Windows) in batch file processing.
• Validate and clean filenames in data import pipelines where preserving the original name is important.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Removes or replaces problematic characters from filenames while preserving the original name and non-ASCII characters whenever possible, using a blacklist approach.

Yes, if you need quick filename sanitization and accept the blacklist trade-off. The package is simple, dependency-free, and handles most common cases well. However, the project is abandoned (last release April 2020), so it will not receive security updates or bug fixes. Use it for non-critical applications or where you can audit and maintain the code yourself if needed.

Install

sanitize-filename on PyPI

pip install sanitize-filename

uv add sanitize-filename

poetry add sanitize-filename

Installing sanitize-filename

Before you install

Installation is frictionless—no runtime dependencies and a pure Python wheel. However, the package is abandoned; the last release was 2020-04-24 and no maintenance activity is evident, so security or compatibility issues would not be addressed.

License in practice

Licensed under MIT (permissive), so you may use, modify, and distribute the package freely in commercial or private projects with minimal restrictions.

Quickstart

pip install sanitize-filename

from sanitize_filename import sanitize

filename = sanitize("A/B/C.txt")
print(filename)  # 'ABC.txt'

Requires Python 3.7 or later.

Verify before relying

• Whether the blacklist approach adequately handles all filesystem-specific reserved names and characters across Windows, macOS, and Linux in practice.
• Whether non-ASCII character preservation works correctly with all Unicode normalization edge cases.

Package facts

Evidence: sanitize_filename-1.2.0-py3-none-any.whl

Tags

More Utilities packages