Skip to main content

A simple, dependency-free, blacklist-based filename sanitizer, for when you want to keep the original filename.

Note that a blacklist based sanitizer will never be as safe as a whitelist based one. In most cases, your best option is to create a safe filename yourself. Your second safest option is to use a whitelist approach (allowing only certain characters). This sanitizer is useful when you want to keep the original filename, including non ascii characters, whenever possible. It might be useful for trusted but dirty input, but should not be used with raw user input!

Installation

pip install sanitize_filename

Usage

from sanitize_filename import sanitize


filename = input("Enter a file name:")
filename = sanitize(filename)

Examples:

> sanitize("A/B/C.txt")
'ABC.txt'

> sanitize("this𓀦filenameḜisあactually...valid.txt")
'this𓀦filenameḜisあactually...valid.txt'

> sanitize("def.")
'def'

> sanitize("NUL")
'__NUL'

> sanitize("..")
'__'

> sanitize("x" * 200 + ".txt", max_bytes=10)
'xxxxxx.txt'

Arguments to sanitize

  • max_bytes sets the maximum number of UTF-8 bytes. Default is 255.

Changelog

  • 1.3.0

    • Add max_bytes argument to sanitize()
    • Filenames are now NFC normalized rather than NFKD, so that e.g. narrow non-break space (common in macOS screenshot names) are kept.
    • Count UTF-8 bytes, not characters, when limiting filename length. This will make long non-ascii filenames shorter than in earlier versions.
    • Blacklist bidi control chars, to avoid e.g. "file\u202etxt.exe" displaying locally as "fileexe.txt"
    • Make sure the result of truncating a filename can not be a reserved word (e.g. CON [...] x.txt)
    • Limit filename extensions to 16 characters, and truncate separately
    • Make sure not to split character sequences when truncating names
    • Do all character removals in one step to speed up execution
  • 1.2.1

    • Fix a bug where a fullwidth character could be used craft path traversal attack
    • Add some missing Windows device names
    • Remove lone surrogates
    • Fix a bug where names could be crafted to end in a dot.
    • Remove C1 range control characters
  • 1.2.0

    • Get rid of os dependent checks; ensure uniform behaviour
    • Now works on long filenames where the non-extensions part consists of only dots
  • 1.1.0

    • Try to preserve filename extensions if possible
  • 1.0.1

    • First release (as 1.0.1 due to a version number mix-up in 1.0.0)
  • 1.0.0-dev3

    • Black list low code point characters (<32)
  • 1.0.0-dev1

    • First version

Metadata

Release files for sanitize-filename 1.3.0

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

Source distribution (sdist)

Source distribution for sanitize-filename 1.3.0
File Size Uploaded Provenance Actions
sanitize_filename-1.3.0.tar.gz 7.8 kB Without provenance Details for sanitize_filename-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sanitize-filename 1.3.0
File Interpreter ABI Platform Actions
sanitize_filename-1.3.0-py3-none-any.whl Python 3 none any Details for sanitize_filename-1.3.0-py3-none-any.whl

Total release size: 13.7 kB

Release files / sanitize_filename-1.3.0.tar.gz

Download URL sanitize_filename-1.3.0.tar.gz
Size 7.8 kB
Tags Source
SHA-256 checksum
How to use checksums
86f0786732ece5cbac4c5817fce55286c1473ae8b122c66a9a143d1a81347c64
BLAKE2b-256 checksum
How to use checksums
7b60709d061056e9d0800e0699f2becabd4c7edc5dce09da0625145df4d70d7a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / sanitize_filename-1.3.0-py3-none-any.whl

Download URL sanitize_filename-1.3.0-py3-none-any.whl
Size 5.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3c5887735c31e0062646b732a1f1ef8683f889f63c4e07fd8c49c7e6460d9414
BLAKE2b-256 checksum
How to use checksums
b90bcfe4c0e2cd0eaa840dcdd5b98ea1cb256b9a7fde4c572fbc84dbf4c936ba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Security for sanitize-filename 1.3.0

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