> 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

🏷️ 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 ↑

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

find_project_root-2.2.0.tar.gz (19.1 kB view details)

Uploaded Apr 28, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

find_project_root-2.2.0-py3-none-any.whl (21.4 kB view details)

Uploaded Apr 28, 2026 Python 3

File details

Details for the file find_project_root-2.2.0.tar.gz.

File metadata

Download URL: find_project_root-2.2.0.tar.gz
Upload date: Apr 28, 2026
Size: 19.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for find_project_root-2.2.0.tar.gz
Algorithm	Hash digest
SHA256	`a32cc43794cc3e2c26a021a44a598aef88ddc78b7527881c6dddd078e6bc9b09`
MD5	`77d8f46a7890c9088618a8edc1a59fb6`
BLAKE2b-256	`3e6739e917239ea556758e24085ce6dfbc8812e82a2879a93dc036e737017e19`

See more details on using hashes here.

Provenance

The following attestation bundles were made for find_project_root-2.2.0.tar.gz:

Publisher: publish-to-pypi-on-new-tag.yml on adamlui/python-utils

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: find_project_root-2.2.0.tar.gz
- Subject digest: a32cc43794cc3e2c26a021a44a598aef88ddc78b7527881c6dddd078e6bc9b09
- Sigstore transparency entry: 1396110117
- Sigstore integration time: Apr 28, 2026
Source repository:
- Permalink: adamlui/python-utils@f6c733a6d7cf8b6d2c69b271088566fea27729c5
- Branch / Tag: refs/tags/find-project-root-2.2.0
- Owner: https://github.com/adamlui
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-to-pypi-on-new-tag.yml@f6c733a6d7cf8b6d2c69b271088566fea27729c5
- Trigger Event: release