{"id":1010,"library":"pathvalidate","title":"Pathvalidate","description":"pathvalidate is a Python library to sanitize/validate a string such as filenames/file-paths/etc. It provides functions to remove invalid characters, replace reserved names, and normalize paths for various operating systems (Linux, Windows, macOS, POSIX, universal). The current version is 3.3.1, and it maintains an active release cadence with regular updates and feature enhancements.","status":"active","version":"3.3.1","language":"python","source_language":"en","source_url":"https://github.com/thombashi/pathvalidate","tags":["path","filename","validation","sanitization","filepath","cross-platform","file-system"],"install":[{"cmd":"pip install pathvalidate","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"validate_filename","correct":"from pathvalidate import validate_filename"},{"symbol":"sanitize_filename","correct":"from pathvalidate import sanitize_filename"},{"symbol":"ValidationError","correct":"from pathvalidate import ValidationError"},{"symbol":"sanitize_filepath","correct":"from pathvalidate import sanitize_filepath"}],"quickstart":{"code":"import sys\nfrom pathvalidate import ValidationError, validate_filename, sanitize_filename, sanitize_filepath\n\n# Example 1: Validate a filename\ntry:\n    validate_filename(\"my:file*name?.txt\")\n    print(\"Filename is valid.\")\nexcept ValidationError as e:\n    print(f\"Validation error: {e}\", file=sys.stderr)\n\n# Example 2: Sanitize a filename\ninvalid_fname = \"my:inval|id*file?.txt\"\nsanitized_fname = sanitize_filename(invalid_fname)\nprint(f\"Sanitized filename '{invalid_fname}' -> '{sanitized_fname}'\")\n\n# Example 3: Sanitize a filepath\ninvalid_fpath = \"/usr/loc:al/my<dir>/invalid?file.log\"\nsanitized_fpath = sanitize_filepath(invalid_fpath)\nprint(f\"Sanitized filepath '{invalid_fpath}' -> '{sanitized_fpath}'\")","lang":"python","description":"This quickstart demonstrates how to validate a filename, and how to sanitize both filenames and file paths, handling potential `ValidationError` exceptions."},"warnings":[{"fix":"Upgrade your Python environment to version 3.9 or higher.","message":"Dropped support for Python 3.7 and 3.8 in v3.2.2. Prior to that, v3.1.0 dropped Python 3.6 support. Users on older Python versions must upgrade to Python 3.9 or newer to use current versions of pathvalidate.","severity":"breaking","affected_versions":">=3.1.0, >=3.2.2"},{"fix":"Update type hints and logic to directly handle `ErrorReason` as the return type for `ValidationError.reason`.","message":"The return type of `ValidationError.reason` changed from `Optional[ErrorReason]` to `ErrorReason` in v3.1.0. Code expecting an `Optional` type for this attribute may need adjustments.","severity":"breaking","affected_versions":">=3.1.0"},{"fix":"Review calls to `FileNameSanitizer` and `FilePathSanitizer` constructors, remove `min_len`, and consider using the new `validator` argument if needed. Catch `ValidationError` instead of `InvalidLengthError`.","message":"In v3.0.0, the `min_len` argument was removed from the constructors of `FileNameSanitizer` and `FilePathSanitizer`, and a `validator` argument was added. Additionally, `InvalidLengthError` was removed, with `ValidationError` now used for length-related issues.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always pass the `platform` argument (e.g., `platform='Windows'`) to validation and sanitization functions if specific OS rules are required.","message":"For platform-specific validation or sanitization, you must explicitly specify the `platform` argument (e.g., 'Windows', 'Linux', 'macOS', 'POSIX') in functions like `validate_filename` or `sanitize_filename`. If omitted, it defaults to 'universal' (most restrictive) for filenames or 'auto' for file paths, which might not match your intended target environment's rules.","severity":"gotcha","affected_versions":"All"},{"fix":"Check `DeprecationWarning` messages during development and update to the recommended alternative functions or methods.","message":"Version 2.5.1 introduced `DeprecationWarning` for some functions. While specific functions are not detailed in release notes, users should pay attention to warnings during execution or linting.","severity":"deprecated","affected_versions":">=2.5.1"}],"env_vars":null,"last_verified":"2026-05-12T22:32:43.605Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install pathvalidate`","cause":"The 'pathvalidate' package is not installed in the Python environment where the code is being run.","error":"ModuleNotFoundError: No module named 'pathvalidate'"},{"fix":"Use `sanitize_filename()` or `sanitize_filepath()` to remove or replace invalid characters before validation, or ensure the input string contains only valid characters. \n\n```python\nfrom pathvalidate import validate_filename, sanitize_filename, ValidationError\n\ntry:\n    validate_filename('fi:l*e/p\"a?t>h|.t<xt')\nexcept ValidationError as e:\n    print(e) # Output: [PV1100] invalid characters found: ...\n\n# Fix:\nsanitized_name = sanitize_filename('fi:l*e/p\"a?t>h|.t<xt')\nprint(sanitized_name) # Output: filepath.txt\nvalidate_filename(sanitized_name) # This will now pass\n```","cause":"The string provided to `validate_filename()` or `validate_filepath()` contains characters that are illegal for filenames or file paths on the specified (or default universal) platform.","error":"ValidationError: [PV1100] invalid characters found"},{"fix":"Use `sanitize_filename()` or `sanitize_filepath()` which automatically handles reserved names by default, or provide a different name. You can also specify a `reserved_name_handler` for custom behavior. \n\n```python\nfrom pathvalidate import validate_filename, sanitize_filename, ValidationError\n\ntry:\n    validate_filename('COM1', platform='Windows')\nexcept ValidationError as e:\n    print(e) # Output: [PV1002] found a reserved name by a platform: 'COM1'\n\n# Fix:\nsanitized_name = sanitize_filename('COM1', platform='Windows')\nprint(sanitized_name) # Output: _COM1\nvalidate_filename(sanitized_name, platform='Windows') # This will now pass\n```","cause":"The filename or filepath string provided to a validation function is a reserved name (e.g., 'CON', 'NUL', 'COM1') on the target operating system, which cannot be used as a filename.","error":"ValidationError: [PV1002] found a reserved name by a platform"},{"fix":"Correct the spelling of the function name to `sanitize_filename` (using 'z').\n\n```python\n# Wrong:\n# from pathvalidate import sanitise_filename\n\n# Correct:\nfrom pathvalidate import sanitize_filename\n\nfilename = 'my/file.txt'\nsanitized = sanitize_filename(filename)\nprint(f'{filename} -> {sanitized}')\n```","cause":"A common misspelling (using 's' instead of 'z') of the `sanitize_filename` function is attempted during import.","error":"ImportError: cannot import name 'sanitise_filename' from 'pathvalidate'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.3.1","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.1,"disk_size":"18.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.1,"disk_size":"18.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.03,"mem_mb":2.1,"disk_size":"18M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.1,"disk_size":"18M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.9,"disk_size":"19.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":1.9,"disk_size":"19.8M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.06,"mem_mb":1.9,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.9,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.5,"disk_size":"11.7M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.5,"disk_size":"11.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":0.04,"mem_mb":1.5,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.5,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.5,"disk_size":"11.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.5,"disk_size":"11.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":0.04,"mem_mb":1.3,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.3,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.1,"disk_size":"17.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.1,"disk_size":"17.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0.04,"mem_mb":2.1,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.1,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}