---
id: py-walk
version: "0.3.3"
license: unclear
license_treatment: permissive
maintenance: dormant
---

# py-walk — Filter filesystem paths based on gitignore-like patterns

License: permissive · Maintenance: dormant · Downloads: 1.4M/mo

## What it is and what it does

py-walk is a Python library that interprets gitignore-style patterns to filter filesystem paths. It provides two main workflows: walking a directory tree and returning only paths that match or don't match a set of patterns, or creating a parser object to test individual paths against patterns on demand. The library aims for Git wildmatch compatibility and includes tests derived from Git's own test suite.

You pass patterns as text, a list, or a .gitignore file, optionally specifying a base directory. The walk function returns a generator of Path objects; you can also filter by file vs. directory mode, or combine ignore and match rules (with ignore taking precedence). It depends only on sly for parsing and supports Python 3.7 through 3.12.

Use it for:

- Build tools or linters that need to offer users a .gitignore-style configuration file to exclude or include paths.
- Interactive scripts that need to quickly retrieve sets of files matching complex constraints without reimplementing gitignore logic.
- Test runners or deployment tools that must respect .gitignore patterns to avoid processing excluded directories.
- File synchronization or backup utilities that want to honor gitignore rules without calling out to Git itself.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Filters filesystem paths using gitignore-style pattern matching, allowing you to walk directories with include/exclude rules or test individual paths against patterns.

Yes, if you need gitignore-compatible pattern matching and can tolerate dormant maintenance. The library is lightweight, has no known vulnerabilities, and solves a specific problem well. However, if you expect active bug fixes or compatibility updates as Git evolves, consider whether the dormant status (657 days since last release) aligns with your project's needs.

## Install

pip install py-walk
uv add py-walk
poetry add py-walk

## Installing py-walk

Before you install: Low install friction with a single runtime dependency (sly). Maintenance is dormant—last commit was 2024-10-26 and no release in 657 days—but the repository remains active and unarchived.

License in practice: MIT license (permissive); you can use, modify, and distribute this package freely with minimal restrictions.

Quickstart:

pip install py-walk

from py_walk import walk

for path in walk('some/directory', ignore=['*.pyc', '__pycache__/']):
    print(path)

Verify before relying:

- Whether the 500+ tests mentioned in the description are still passing against current Git versions.
- Whether dormant status means bug fixes or pattern compatibility updates are unlikely going forward.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 1.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

gitignore pattern matching, filesystem path filtering, directory walk with patterns, gitignore-compatible rules, path matching library, path-filtering, gitignore-compatible

[View on SkillFed](https://skillfed.io/packages/py-walk) · [View on PyPI](https://pypi.org/project/py-walk/)