> find-project-root

Locate project root via custom markers.

About

find-project-root is a lightweight utility that traverses up from a given path until it finds a project marker.

• Lightweight — < 100 KB
• Path flexibility — accepts strings, Path objects, or current working dir
• Customizable markers — provide your own or use defaults
• Multi-env support — use via API or CLI

Installation

pip install find-project-root

API usage

import find_project_root

# Find from current dir
root = find_project_root()
print(root) # e.g. => /home/user/projects/your-project

Note: Most type checkers will falsely warn find_project_root is not a callable module because they are incapable of analyzing runtime behavior (where the module is replaced w/ a function for cleaner, direct access). You can safely suppress such warnings using # type: ignore.

Available options:

Examples:

Start from specific path:

root = find_project_root(path='assets/images')

Limit search depth:

root = find_project_root(max_depth=3)

Use custom markers:

root = find_project_root(markers=['.git', 'pyproject.toml', 'requirements.txt'])

Combine options:

root = find_project_root(path='src', max_depth=5, markers=['manifest.json'])

Command line usage

find-project-root  # or projectroot
# e.g. => 'e:\python\utils\translate-messages'

Command line options:

Examples:

Start from specific path:

find-project-root --path="assets/images"

Limit search depth:

find-project-root --max_depth=3

Use custom markers:

find-project-root --markers=.git,pyproject.toml,requirements.txt

Combine options:

find-project-root --path=src --max-depth=5 --markers=.manifest.json

Config file

Run find-project-root --init to create .project-root.config.json5 in your project root to set default options.

Example defaults:

{
  "path": "",     // starting dir to search for project root (default: CWD)
  "max_depth": 9, // max levels to traverse up
  "markers": ""   // custom marker files to look for
}

Note: CLI arguments always override config file.

MIT License

Copyright © 2026 Adam Lui

Related

🏷️ project-markers - Common project root markers.
📊 get-min-py - Get the minimum Python version required for a PyPI package.

More Python utilities / Discuss / Report bug / Report vulnerability / Back to top ↑