Metadata-Version: 2.4
Name: find-project-root
Version: 2.2.0
Summary: Locate project root via custom markers.
Author-email: Adam Lui <adam@kudoai.com>
License-Expression: MIT
Project-URL: Changelog, https://github.com/adamlui/python-utils/releases/tag/find-project-root-2.2.0
Project-URL: Documentation, https://github.com/adamlui/python-utils/tree/main/find-project-root/docs
Project-URL: Funding, https://github.com/sponsors/adamlui
Project-URL: Homepage, https://github.com/adamlui/python-utils/tree/main/find-project-root/#readme
Project-URL: Issues, https://github.com/adamlui/python-utils/issues
Project-URL: Releases, https://github.com/adamlui/python-utils/releases
Project-URL: Repository, https://github.com/adamlui/python-utils
Keywords: detect,detection,dev-tool,directory,filesystem,git-root,locate-root,marker-files,path-finder,project-root,root-detection
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: <4,>=3.8
Description-Content-Type: text/markdown
License-File: docs/LICENSE.md
Requires-Dist: colorama<1,>=0.4.6; platform_system == "Windows"
Requires-Dist: is-unicode-supported<2,>=1.2.1
Requires-Dist: json5<1,>=0.14.0
Requires-Dist: non-latin-locales<2,>=1.0.5
Requires-Dist: project-markers<2,>=1.0.4
Requires-Dist: sys-lang<2,>=1.0.1
Provides-Extra: dev
Requires-Dist: nox>=2026.4.10; extra == "dev"
Requires-Dist: pre-commit<5,>=4.5.1; extra == "dev"
Requires-Dist: remove-json-keys<2,>=1.10.1; extra == "dev"
Requires-Dist: tomli<3,>=2.4.1; extra == "dev"
Requires-Dist: tomli-w<2,>=1.2.0; extra == "dev"
Requires-Dist: translate-messages<2,>=1.10.1; extra == "dev"
Dynamic: license-file

<a id="top"></a>

# > find-project-root

<a href="https://pepy.tech/projects/find-project-root?versions=*">
    <img height=31 src="https://img.shields.io/pepy/dt/find-project-root?logo=weightsandbiases&color=af68ff&logoColor=white&labelColor=464646&style=for-the-badge"></a>
<a href="https://github.com/adamlui/python-utils/releases/tag/find-project-root-2.2.0">
    <img height=31 src="https://img.shields.io/badge/Latest_Build-2.2.0-32fcee.svg?logo=icinga&logoColor=white&labelColor=464646&style=for-the-badge"></a>
<a href="https://github.com/adamlui/python-utils/blob/main/find-project-root/docs/LICENSE.md">
    <img height=31 src="https://img.shields.io/badge/License-MIT-f99b27.svg?logo=internetarchive&logoColor=white&labelColor=464646&style=for-the-badge"></a>
<a href="https://www.codefactor.io/repository/github/adamlui/python-utils">
    <img height=31 src="https://img.shields.io/codefactor/grade/github/adamlui/python-utils?label=Code+Quality&logo=codefactor&logoColor=white&labelColor=464646&color=a0fc55&style=for-the-badge"></a>
<a href="https://sonarcloud.io/component_measures?metric=vulnerabilities&selected=adamlui_python-utils%3Afind-project-root&id=adamlui_python-utils">
    <img height=31 src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fsonarcloud.io%2Fapi%2Fmeasures%2Fcomponent%3Fcomponent%3Dadamlui_python-utils%3Afind-project-root%26metricKeys%3Dvulnerabilities&query=%24.component.measures.0.value&style=for-the-badge&logo=sonar&logoColor=white&labelColor=464646&label=Vulnerabilities&color=fafc74"></a>

> ### _Locate project root via custom markers._

<a href="#"><img style="height:10px ; width:100%" src="https://cdn.jsdelivr.net/gh/adamlui/js-utils@7da7074/assets/images/separators/aqua-gradient.png"></a>

## 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](#api-usage) or [CLI](#command-line-usage)

<hr>

## Installation

```bash
pip install find-project-root
```

<hr>

## API usage

```py
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`][project-markers-json] list

### Examples:

Start from specific path:

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

Limit search depth:

```py
root = find_project_root(max_depth=3)
```

Use custom markers:

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

Combine options:

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

<hr>

## Command line usage

```bash
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`][project-markers-json] list)
| `-h`, `--help`      | Show help screen
| `-v`, `--version`   | Show version
| `--docs`            | Open docs URL

### Examples:

Start from specific path:

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

Limit search depth:

```bash
find-project-root --max_depth=3
```

Use custom markers:

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

Combine options:

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

<hr>

## Config file

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

Example defaults:

```json5
{
  "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._

<hr>


## MIT License

Copyright © 2026 [Adam Lui](https://github.com/adamlui)

<hr>

## Related

🏷️ [project-markers][project-markers-gh] - Common project root markers.
<br>📊 [get-min-py](https://github.com/adamlui/python-utils/tree/main/get-min-py/#readme) - Get the minimum Python version required for a PyPI package.

<a href="#"><img style="height:10px ; width:100%" src="https://cdn.jsdelivr.net/gh/adamlui/python-utils@b8b2932/assets/images/separators/aqua-gradient.png"></a>

<picture><source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/adamlui/python-utils@760599e/assets/images/icons/home/white/icon32x27.png"><img height=13 src="https://cdn.jsdelivr.net/gh/adamlui/python-utils@760599e/assets/images/icons/home/dark-gray/icon32x27.png"></picture> <a href=https://github.com/adamlui/python-utils/#readme>**More Python utilities**</a> /
<a href="https://github.com/adamlui/python-utils/discussions">Discuss</a> /
<a href="https://github.com/adamlui/python-utils/issues">Report bug</a> /
<a href="mailto:security@tidelift.com">Report vulnerability</a> /
<a href="#top">Back to top ↑</a>

[project-markers-gh]: https://github.com/adamlui/python-utils/tree/main/project-markers/#readme
[project-markers-json]: https://cdn.jsdelivr.net/gh/adamlui/python-utils/project-markers/src/project_markers/project-markers.json
