find-project-root 1.0.3

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.

• Minimal dependencies — only uses project-markers (~4 KB module)
• Path flexibility — accepts strings, Path objects, or current working dir
• Customizable markers — provide your own or use defaults
• Multi-Python support — from Python 2.6 thru 3.15+

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'])

MIT License

Copyright © 2026 Adam Lui.

Back to top ↑