Registry / serialization / sanitize-filename

sanitize-filename

library1.2.0pypypi✓ verified 85d ago

sanitize-filename is a simple, dependency-free, blacklist-based filename sanitizer for Python. It focuses on preserving the original filename as much as possible, including non-ASCII characters, while removing characters unsafe for common file systems. The current version is 1.2.0, released in April 2020. It's a stable library with infrequent updates, primarily for minor fixes and behavior uniformity.

serialization

pip install sanitize-filename

package ↗homepage ↗

INSTALL

IMPORT

SIG · SANITIZE-FILENAME

sanitize-filename

serializationpythonv1.2.0

Install

1.8s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.8s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sanitize

✓ from sanitize_filename import sanitize

This quickstart demonstrates how to import and use the `sanitize` function to clean up a filename string, removing characters that are typically invalid or problematic across various file systems.

from sanitize_filename import sanitize # Example usage unsafe_filename = 'My/Document:with"illegal*chars?.txt' safe_filename = sanitize(unsafe_filename) print(f"Original: {unsafe_filename}") print(f"Sanitized: {safe_filename}") # Another example with reserved names or paths unsafe_path = '../etc/passwd' safe_path = sanitize(unsafe_path) print(f"Original: {unsafe_path}") print(f"Sanitized: {safe_path}")

Debug

Known issues

gotchaThis library uses a blacklist-based approach. While effective for common cases, a whitelist approach (allowing only known safe characters) is generally safer for highly sensitive applications or when dealing with untrusted user input, as blacklists can be incomplete.

fix

For maximum security, consider supplementing with additional validation or using a whitelist approach if applicable to your use case.

affects: <=1.2.0

gotchaSanitizing filenames can result in non-unique names if different unsafe inputs resolve to the same safe filename (e.g., 'file?.txt' and '*file*.txt' both become 'file.txt'). This can lead to overwriting files if not handled.

fix

Implement additional logic to ensure uniqueness for file storage, such as appending a timestamp or a hash to the filename before saving.

affects: <=1.2.0

breakingPrior to version 1.2.0, filename sanitization behavior might have been OS-dependent, and issues could occur with long filenames where the non-extension part consisted solely of dots. Version 1.2.0 introduced uniform behavior across operating systems and fixed this specific long filename issue.

fix

Upgrade to version 1.2.0 or higher to ensure consistent cross-platform behavior and handle edge cases with dot-only filenames.

affects: <1.2.0

Errors

Common errors & fixes

File operations fail due to 'Is a directory' or 'No such file or directory' errors even after sanitizing.

The `sanitize` function only cleans a *filename*, not a *file path*. It removes characters illegal in filenames but does not prevent path traversal sequences (e.g., `../`). Passing a full path with malicious elements to `sanitize` might not fully mitigate path traversal risks.

fix

Always separate the path from the filename. Sanitize only the filename component, and validate/construct the directory path independently to prevent directory traversal attacks (e.g., using `os.path.basename` and `os.path.join`).

Sanitized filename results in an empty string.

For certain inputs, such as `..`, ``, or `/.`, the `sanitize` function removes all invalid characters, which can result in an empty string. Attempting to create a file with an empty name will typically fail.

fix

Add a check after sanitization: `sanitized_name = sanitize(input_name); if not sanitized_name: sanitized_name = 'untitled'`. Provide a sensible default filename if the sanitized output is empty.

Upgrade

Version history

1.2.0latest on PyPI · released Apr 24, 2020

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/sanitize-filename/ ↗

homepagehttps://gitlab.com/jplusplus/sanitize-filename ↗