{"id":7698,"library":"sanitize-filename","title":"Filename Sanitizer","description":"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.","status":"maintenance","version":"1.2.0","language":"en","source_language":"en","source_url":"https://pypi.org/project/sanitize-filename/","tags":["filename","sanitize","security","path","cross-platform"],"install":[{"cmd":"pip install sanitize-filename","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"sanitize","correct":"from sanitize_filename import sanitize"}],"quickstart":{"code":"from sanitize_filename import sanitize\n\n# Example usage\nunsafe_filename = 'My/Document:with\"illegal*chars?.txt'\nsafe_filename = sanitize(unsafe_filename)\nprint(f\"Original: {unsafe_filename}\")\nprint(f\"Sanitized: {safe_filename}\")\n\n# Another example with reserved names or paths\nunsafe_path = '../etc/passwd'\nsafe_path = sanitize(unsafe_path)\nprint(f\"Original: {unsafe_path}\")\nprint(f\"Sanitized: {safe_path}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"For maximum security, consider supplementing with additional validation or using a whitelist approach if applicable to your use case.","message":"This 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.","severity":"gotcha","affected_versions":"<=1.2.0"},{"fix":"Implement additional logic to ensure uniqueness for file storage, such as appending a timestamp or a hash to the filename before saving.","message":"Sanitizing 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.","severity":"gotcha","affected_versions":"<=1.2.0"},{"fix":"Upgrade to version 1.2.0 or higher to ensure consistent cross-platform behavior and handle edge cases with dot-only filenames.","message":"Prior 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.","severity":"breaking","affected_versions":"<1.2.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`).","cause":"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.","error":"File operations fail due to 'Is a directory' or 'No such file or directory' errors even after sanitizing."},{"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.","cause":"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.","error":"Sanitized filename results in an empty string."}]}