find-project-root is a lightweight utility that traverses up from a given path until it finds a project marker.
- Minimal dependencies — only uses project-markers (~4 KB module)
- Path flexibility — accepts strings,
Pathobjects, or current working dir - Customizable markers — provide your own or use defaults
- Multi-Python support — from Python 2.6 thru 3.15+
pip install find-project-rootimport find_project_root
# Find from current dir
root = find_project_root()
print(root) # e.g. => /home/user/projects/your-projectNote: 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.
| 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 |
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'])Copyright © 2026 Adam Lui
🏷️ project-markers - Common project root markers.
📊 get-min-py - Get the minimum Python version required for a PyPI package.
