Pathvalidate

3.3.1 verified Tue May 12 auth: no python install: verified

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.

pip install pathvalidate

Common errors

error ModuleNotFoundError: No module named 'pathvalidate' ↓

cause The 'pathvalidate' package is not installed in the Python environment where the code is being run.

fix

Install the package using pip: pip install pathvalidate

error ValidationError: [PV1100] invalid characters found ↓

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.

fix

Use sanitize_filename() or sanitize_filepath() to remove or replace invalid characters before validation, or ensure the input string contains only valid characters.

from pathvalidate import validate_filename, sanitize_filename, ValidationError

try:
    validate_filename('fi:l*e/p"a?t>h|.t<xt')
except ValidationError as e:
    print(e) # Output: [PV1100] invalid characters found: ...

# Fix:
sanitized_name = sanitize_filename('fi:l*e/p"a?t>h|.t<xt')
print(sanitized_name) # Output: filepath.txt
validate_filename(sanitized_name) # This will now pass

error ValidationError: [PV1002] found a reserved name by a platform ↓

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.

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.

from pathvalidate import validate_filename, sanitize_filename, ValidationError

try:
    validate_filename('COM1', platform='Windows')
except ValidationError as e:
    print(e) # Output: [PV1002] found a reserved name by a platform: 'COM1'

# Fix:
sanitized_name = sanitize_filename('COM1', platform='Windows')
print(sanitized_name) # Output: _COM1
validate_filename(sanitized_name, platform='Windows') # This will now pass

error ImportError: cannot import name 'sanitise_filename' from 'pathvalidate' ↓

cause A common misspelling (using 's' instead of 'z') of the `sanitize_filename` function is attempted during import.

fix

Correct the spelling of the function name to sanitize_filename (using 'z').

# Wrong:
# from pathvalidate import sanitise_filename

# Correct:
from pathvalidate import sanitize_filename

filename = 'my/file.txt'
sanitized = sanitize_filename(filename)
print(f'{filename} -> {sanitized}')

Warnings

breaking 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. ↓

fix Upgrade your Python environment to version 3.9 or higher.

breaking 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. ↓

fix Update type hints and logic to directly handle `ErrorReason` as the return type for `ValidationError.reason`.

breaking 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. ↓

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`.

gotcha 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. ↓

fix Always pass the `platform` argument (e.g., `platform='Windows'`) to validation and sanitization functions if specific OS rules are required.

deprecated 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. ↓

fix Check `DeprecationWarning` messages during development and update to the recommended alternative functions or methods.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.05s 18.0M

3.10 alpine (musl) - - 0.05s 18.0M

3.10 slim (glibc) wheel 1.5s 0.03s 18M

3.10 slim (glibc) - - 0.04s 18M

3.11 alpine (musl) wheel - 0.06s 19.8M

3.11 alpine (musl) - - 0.08s 19.8M

3.11 slim (glibc) wheel 1.6s 0.06s 20M

3.11 slim (glibc) - - 0.06s 20M

3.12 alpine (musl) wheel - 0.04s 11.7M

3.12 alpine (musl) - - 0.06s 11.7M

3.12 slim (glibc) wheel 1.4s 0.04s 12M

3.12 slim (glibc) - - 0.04s 12M

3.13 alpine (musl) wheel - 0.04s 11.5M

3.13 alpine (musl) - - 0.04s 11.3M

3.13 slim (glibc) wheel 1.4s 0.04s 12M

3.13 slim (glibc) - - 0.04s 12M

3.9 alpine (musl) wheel - 0.04s 17.5M

3.9 alpine (musl) - - 0.06s 17.5M

3.9 slim (glibc) wheel 1.8s 0.04s 18M

3.9 slim (glibc) - - 0.04s 18M

Imports

validate_filename

from pathvalidate import validate_filename

sanitize_filename

from pathvalidate import sanitize_filename

ValidationError

from pathvalidate import ValidationError

sanitize_filepath

from pathvalidate import sanitize_filepath

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to validate a filename, and how to sanitize both filenames and file paths, handling potential `ValidationError` exceptions.

import sys
from pathvalidate import ValidationError, validate_filename, sanitize_filename, sanitize_filepath

# Example 1: Validate a filename
try:
    validate_filename("my:file*name?.txt")
    print("Filename is valid.")
except ValidationError as e:
    print(f"Validation error: {e}", file=sys.stderr)

# Example 2: Sanitize a filename
invalid_fname = "my:inval|id*file?.txt"
sanitized_fname = sanitize_filename(invalid_fname)
print(f"Sanitized filename '{invalid_fname}' -> '{sanitized_fname}'")

# Example 3: Sanitize a filepath
invalid_fpath = "/usr/loc:al/my<dir>/invalid?file.log"
sanitized_fpath = sanitize_filepath(invalid_fpath)
print(f"Sanitized filepath '{invalid_fpath}' -> '{sanitized_fpath}'")