Summary

pathvalidate is a Python library to sanitize/validate a string such as filenames/file-paths/etc.

Features

Sanitize/Validate a string as a:
- file name
- file path
Sanitize will do:
- Remove invalid characters for a target platform
- Replace reserved names for a target platform
- Normalize
- Remove unprintable characters
Argument validator/sanitizer for argparse and click
Multi platform support:
- Linux
- Windows
- macOS
- POSIX: POSIX-compliant systems (Linux, macOS, etc.)
- universal: platform independent
Multibyte character support

CLI tool

You can find this package’s command line interface tool at the pathvalidate-cli repository.

Examples

Sanitize a filename

Sample Code:

from pathvalidate import sanitize_filename

fname = "fi:l*e/p\"a?t>h|.t<xt"
print(f"{fname} -> {sanitize_filename(fname)}\n")

fname = "\0_a*b:c<d>e%f/(g)h+i_0.txt"
print(f"{fname} -> {sanitize_filename(fname)}\n")

Output:

fi:l*e/p"a?t>h|.t<xt -> filepath.txt

_a*b:c<d>e%f/(g)h+i_0.txt -> _abcde%f(g)h+i_0.txt

The default target platform is universal. i.e. the sanitized file name is valid for any platform.

Sanitize a filepath

Sample Code:

from pathvalidate import sanitize_filepath

fpath = "fi:l*e/p\"a?t>h|.t<xt"
print(f"{fpath} -> {sanitize_filepath(fpath)}\n")

fpath = "\0_a*b:c<d>e%f/(g)h+i_0.txt"
print(f"{fpath} -> {sanitize_filepath(fpath)}\n")

Output:

fi:l*e/p"a?t>h|.t<xt -> file/path.txt

_a*b:c<d>e%f/(g)h+i_0.txt -> _abcde%f/(g)h+i_0.txt

Validate a filename

Sample Code:

import sys
from pathvalidate import ValidationError, validate_filename

try:
    validate_filename("fi:l*e/p\"a?t>h|.t<xt")
except ValidationError as e:
    print(f"{e}\n", file=sys.stderr)

try:
    validate_filename("COM1")
except ValidationError as e:
    print(f"{e}\n", file=sys.stderr)

Output:

[PV1100] invalid characters found: platform=universal, description=invalids=('/'), value='fi:l*e/p"a?t>h|.t<xt'

[PV1002] found a reserved name by a platform: 'COM1' is a reserved name, platform=universal, reusable_name=False

Check a filename

Sample Code:

from pathvalidate import is_valid_filename, sanitize_filename

fname = "fi:l*e/p\"a?t>h|.t<xt"
print(f"is_valid_filename('{fname}') return {is_valid_filename(fname)}\n")

sanitized_fname = sanitize_filename(fname)
print(f"is_valid_filename('{sanitized_fname}') return {is_valid_filename(sanitized_fname)}\n")

Output:

is_valid_filename('fi:l*e/p"a?t>h|.t<xt') return False

is_valid_filename('filepath.txt') return True

filename/filepath validator for argparse

Sample Code:

from argparse import ArgumentParser

from pathvalidate.argparse import validate_filename_arg, validate_filepath_arg

parser = ArgumentParser()
parser.add_argument("--filename", type=validate_filename_arg)
parser.add_argument("--filepath", type=validate_filepath_arg)
options = parser.parse_args()

if options.filename:
    print(f"filename: {options.filename}")

if options.filepath:
    print(f"filepath: {options.filepath}")

Output:

$ ./examples/argparse_validate.py --filename eg
filename: eg
$ ./examples/argparse_validate.py --filename e?g
usage: argparse_validate.py [-h] [--filename FILENAME] [--filepath FILEPATH]
argparse_validate.py: error: argument --filename: [PV1100] invalid characters found: invalids=(':'), value='e:g', platform=Windows

filename/filepath sanitizer for argparse

Sample Code:

from argparse import ArgumentParser

from pathvalidate.argparse import sanitize_filename_arg, sanitize_filepath_arg


parser = ArgumentParser()
parser.add_argument("--filename", type=sanitize_filename_arg)
parser.add_argument("--filepath", type=sanitize_filepath_arg)
options = parser.parse_args()

if options.filename:
    print("filename: {}".format(options.filename))

if options.filepath:
    print("filepath: {}".format(options.filepath))

Output:

$ ./examples/argparse_sanitize.py --filename e/g
filename: eg

filename/filepath validator for click

Sample Code:

import click

from pathvalidate.click import validate_filename_arg, validate_filepath_arg


@click.command()
@click.option("--filename", callback=validate_filename_arg)
@click.option("--filepath", callback=validate_filepath_arg)
def cli(filename: str, filepath: str) -> None:
    if filename:
        click.echo(f"filename: {filename}")
    if filepath:
        click.echo(f"filepath: {filepath}")


if __name__ == "__main__":
    cli()

Output:

$ ./examples/click_validate.py --filename ab
filename: ab
$ ./examples/click_validate.py --filepath e?g
Usage: click_validate.py [OPTIONS]
Try 'click_validate.py --help' for help.

Error: Invalid value for '--filename': [PV1100] invalid characters found: invalids=('?'), value='e?g', platform=Windows

filename/filepath sanitizer for click

Sample Code:

import click

from pathvalidate.click import sanitize_filename_arg, sanitize_filepath_arg


@click.command()
@click.option("--filename", callback=sanitize_filename_arg)
@click.option("--filepath", callback=sanitize_filepath_arg)
def cli(filename, filepath):
    if filename:
        click.echo(f"filename: {filename}")
    if filepath:
        click.echo(f"filepath: {filepath}")


if __name__ == "__main__":
    cli()

Output:

$ ./examples/click_sanitize.py --filename a/b
filename: ab

For more information

More examples can be found at https://pathvalidate.rtfd.io/en/latest/pages/examples/index.html

Installation

Installation: pip

pip install pathvalidate

Installation: conda

conda install conda-forge::pathvalidate

Installation: apt

sudo add-apt-repository ppa:thombashi/ppa
sudo apt update
sudo apt install python3-pathvalidate

Dependencies

Python 3.9+ no external dependencies.

Documentation

https://pathvalidate.rtfd.io/

Sponsors

Become a sponsor

Release files for pathvalidate 3.3.1

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

Source distribution (sdist)

Source distribution for pathvalidate 3.3.1
File	Size	Uploaded
pathvalidate-3.3.1.tar.gz	63.3 kB	Jun 15, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for pathvalidate 3.3.1
File	Interpreter	ABI	Platform	Reset
pathvalidate-3.3.1-py3-none-any.whl 24.3 kB Jun 15, 2025	Python 3	none	any	Details

Total release size: 87.6 kB

Release files / pathvalidate-3.3.1.tar.gz

Download URL	pathvalidate-3.3.1.tar.gz
Size	63.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`b18c07212bfead624345bb8e1d6141cdcf15a39736994ea0b94035ad2b1ba177`
BLAKE2b-256 checksum How to use checksums	`fa2a52a8da6fe965dea6192eb716b357558e103aea0a1e9a8352ad575a8406ca`
Upload date	Jun 15, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.12.9`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/thombashi/pathvalidate
Publishing commit: github.com/thombashi/pathvalidate/tree/5a4aeb3bb85513daa68863ddee12c39aae8d5a55

Workflow

Publishing configuration: github.com/thombashi/pathvalidate/blob/5a4aeb3bb85513daa68863ddee12c39aae8d5a55/.github/workflows/release.yml
Publishing logs: github.com/thombashi/pathvalidate/actions/runs/15661585404/attempts/1

Artifact

Subject: pathvalidate-3.3.1.tar.gz
SHA-256 checksum: b18c07212bfead624345bb8e1d6141cdcf15a39736994ea0b94035ad2b1ba177 Verifying attestations

Release files / pathvalidate-3.3.1-py3-none-any.whl

Download URL	pathvalidate-3.3.1-py3-none-any.whl
Size	24.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5263baab691f8e1af96092fa5137ee17df5bdfbd6cff1fcac4d6ef4bc2e1735f`
BLAKE2b-256 checksum How to use checksums	`9a70875f4a23bfc4731703a5835487d0d2fb999031bd415e7d17c0ae615c18b7`
Upload date	Jun 15, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.12.9`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/thombashi/pathvalidate
Publishing commit: github.com/thombashi/pathvalidate/tree/5a4aeb3bb85513daa68863ddee12c39aae8d5a55

Workflow

Publishing configuration: github.com/thombashi/pathvalidate/blob/5a4aeb3bb85513daa68863ddee12c39aae8d5a55/.github/workflows/release.yml
Publishing logs: github.com/thombashi/pathvalidate/actions/runs/15661585404/attempts/1

Artifact

Subject: pathvalidate-3.3.1-py3-none-any.whl
SHA-256 checksum: 5263baab691f8e1af96092fa5137ee17df5bdfbd6cff1fcac4d6ef4bc2e1735f Verifying attestations