---
id: trailrunner
version: "1.4.0"
license: unclear
license_treatment: permissive
maintenance: dormant
---

# trailrunner — Run things on paths

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

## What it is and what it does

trailrunner is a lightweight library for discovering files in a project directory while respecting .gitignore rules, and then running arbitrary functions on those files in parallel. It exposes three main functions: walk() to list files in a path tree, run() to execute a function on a list of paths using a process pool, and walk_and_run() to combine both operations. The library is designed for developer tools like linters and formatters that need to batch-process project files in a predictable, .gitignore-aware manner.

The package depends only on pathspec for .gitignore parsing and uses Python's built-in multiprocessing for parallelism. It is classified as Production/Stable but has been dormant since March 2023, with no recent active maintenance. Installation is straightforward with minimal dependencies, making it a low-friction addition to a project.

Use it for:

- Implement a linter or code formatter that discovers and processes all project files while skipping ignored paths.
- Batch-process files in parallel for tasks like syntax validation or metadata extraction across a codebase.
- Build a developer tool that walks a project tree and applies a function to each file, respecting project-level .gitignore rules.
- Parallelize file operations (e.g., checksumming, transformation) across many files in a single call.

## Worth the install?

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

Walk filesystem paths while respecting .gitignore rules, and execute functions on found files using a process pool for parallelism.

Yes, for developer tools and batch file processing. The package is stable, has minimal dependencies, and solves a specific problem well. The dormant maintenance status is not a concern for a mature, narrow-scope utility with no known vulnerabilities. Install it if you need .gitignore-aware file discovery with built-in parallelism; skip it if you need active maintenance or ongoing feature development.

## Install

pip install trailrunner
uv add trailrunner
poetry add trailrunner

## Installing trailrunner

Before you install: Low install friction; depends only on pathspec. Dormant maintenance status (last release March 2023, last commit July 2024) means no active development, but the package is classified as Production/Stable and has seen no recent changes to suggest instability.

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

Quickstart:

from pathlib import Path
from trailrunner import walk, run, walk_and_run

# Walk a directory respecting .gitignore
files = walk(Path('.'))

# Run a function on each path in parallel
results = run(files, str)

# Or walk and run in one call
results = walk_and_run([Path('.')], str)

Requires Python 3.7 or newer.

Verify before relying:

- Whether the process pool size is configurable or uses a default based on system CPU count.
- Performance characteristics when walking very large directory trees.
- Behavior when .gitignore files are nested at multiple levels in the tree.

## Package facts

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

## Tags

walk filesystem with gitignore, run functions on files in parallel, batch process project files, path traversal with filtering, multiprocess file operations, linter file discovery, project-aware file walking, file-walking, gitignore-aware, multiprocessing

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