Registry / devops / pyprojroot

pyprojroot

JSON →
library0.3.0pypypi✓ verified 87d ago

pyprojroot is a Python library that facilitates project-oriented workflows by helping to find the project's root directory and construct paths relative to it. Inspired by R's `rprojroot` and `here` packages, it uses common project markers like `.git`, `setup.py`, or `requirements.txt` to locate the root. The current version is 0.3.0, and it's maintained with releases addressing improvements and compatibility.

pip install pyprojroot
INSTALL
IMPORT
SIG · PYPROJROOT
P
pyprojroot
devopspythonv0.3.0
Install
1.6s avg
Import
23ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.025s · 18.1MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.6s · import 0.021s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

here
from pyprojroot.here import here
find_root
import pyprojroot root_path = pyprojroot.find_root(pyprojroot.has_dir('.git'))
For programmatic root finding, often combined with a criterion from pyprojroot.criterion.

This quickstart demonstrates how to use `here()` to find the project root and then construct paths to files or directories relative to it. It assumes a project structure with a root marker (like `.git`) and uses `pathlib.Path` objects for robust path manipulation. The example creates temporary files to be runnable.

import os from pyprojroot.here import here from pathlib import Path # Simulate a project structure for demonstration # In a real project, you would have a .git or other marker in the root. # And your data/notebooks would be actual directories. # Create a dummy project root indicator (e.g., .git directory) project_root_indicator = Path.cwd() / ".git" project_root_indicator.mkdir(exist_ok=True) # Create a dummy data directory and file data_dir = here() / "data" data_dir.mkdir(parents=True, exist_ok=True) data_file = data_dir / "my_data.csv" data_file.write_text("column1,column2\n1,A\n2,B") print(f"Project root (found by pyprojroot): {here()}") print(f"Absolute path to my_data.csv: {here('data/my_data.csv')}") # Example of reading the data using a common library (e.g., pandas) try: import pandas as pd df = pd.read_csv(here('data/my_data.csv')) print("\nData loaded successfully with pandas:") print(df) except ImportError: print("\nInstall pandas (pip install pandas) to run the DataFrame example.") # Clean up dummy project indicator and data project_root_indicator.rmdir() data_file.unlink() data_dir.rmdir()
Debug
Known issues
gotchapyprojroot relies on specific 'root indicators' (e.g., `.git`, `setup.py`, `requirements.txt`, `.here`) to identify the project root. If your project lacks these common markers, or if the current working directory is not within a project containing such a marker, it may fail to find the root or find an unexpected root.
fix
Ensure your project's root directory contains at least one of the default root indicators (e.g., initialize a Git repository with `.git`, or add a `requirements.txt` file). For custom markers, use `pyprojroot.find_root` with a `pyprojroot.criterion`.
affects: All versions
gotchaWhile `pyprojroot` returns `pathlib.Path` objects, its primary value is in robustly *finding* the project root, a task `pathlib` alone doesn't directly solve across varied execution contexts (e.g., scripts vs. notebooks). New users sometimes overlook this distinction.
fix
Understand that `pyprojroot` complements `pathlib` by providing a reliable starting point for relative paths within a project, regardless of the current working directory. `pathlib` then provides the elegant API for path manipulation.
affects: All versions
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'data/my_file.csv'
The `here()` function could not find a project root indicator (e.g., .git, setup.py) in the current directory or its parent directories, or the path relative to the root was incorrect.
fix
Ensure a project root indicator exists in a parent directory. If running a script, make sure the current working directory or one of its parents contains a recognized marker. Double-check the path passed to `here()` is correct relative to your actual project root.
ModuleNotFoundError: No module named 'pyprojroot.here'
The `pyprojroot` library is either not installed, or there's a typo in the import statement.
fix
Install the library using `pip install pyprojroot`. Verify the import statement: `from pyprojroot.here import here` is for the common `here` function, while `import pyprojroot` is for the top-level module.
Upgrade
Version history
0.3.0latest on PyPI · released Mar 13, 2023
Audit
Dependencies

No dependency data recorded yet.

Agent activity
22 hits · last 30 days
node
18
OpenAI (training)
1
Resources
pyprojroot — pip install pyprojroot · libregistry