find-project-root 2.2.0

Locate project root via custom markers.

> 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:

Name	Type	Description	Default Value
path	str, Path or None	Starting directory to search from.	None (current working dir)
max_depth	int	Max levels to traverse up.	9
markers	List[str] or None	Custom marker files to look for.	project-markers list

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:

Option	Description
-p, --path	Starting dir to search for project root (default: CWD)
-d, --max-depth	Max levels to traverse up (default: 9)
-m, --markers	Custom marker files to look for (default: project-markers list)
-h, --help	Show help screen
-v, --version	Show version
--docs	Open docs URL

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 ↑