pyrootutils

What it is and what it does

pyrootutils solves the common problem of Python scripts failing or requiring complex relative imports when run from different working directories. It locates your project root by searching for a marker file (like .git, .project-root, or pyproject.toml) and then configures your Python environment in one step: setting PYTHONPATH so imports work relative to the root, changing the working directory, loading .env variables via its python-dotenv dependency, and optionally setting a PROJECT_ROOT environment variable.

The package is designed for developers who want scripts and notebooks to work consistently regardless of where they're executed from. It's particularly useful in projects with nested directories, notebooks in subdirectories, or teams running scripts from different locations. The setup is a single function call, making it lightweight and easy to integrate into existing projects.

Use it for:

• Run Jupyter notebooks from nested subdirectories while importing from the project root
• Execute scripts from any directory without path-related failures or complex ../../../ imports
• Automatically load environment variables from .env without manual configuration in each script
• Set up CI/CD pipelines where scripts may be invoked from varying working directories
• Simplify data science projects where data paths and module imports need consistent root references

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Finds your project root directory and configures Python paths, working directories, and environment variables in one call, so scripts work consistently regardless of where they're run from.

Yes, if you work with multi-directory Python projects, notebooks, or scripts that need to run from different locations. The single-function setup and low install friction make it a practical utility. The active maintenance and zero known vulnerabilities support confidence in use. The lack of recent releases is not a concern given the package's simplicity and stable scope.

Install

pyrootutils on PyPI

pip install pyrootutils

uv add pyrootutils

poetry add pyrootutils

Installing pyrootutils

Before you install

Low friction install with a single runtime dependency (python-dotenv). Maintenance status is active with recent commits, though the package itself has not had a release since 2022-06-09.

License in practice

MIT license is permissive, allowing free use, modification, and distribution with minimal restrictions.

Quickstart

pip install pyrootutils

import pyrootutils

root = pyrootutils.setup_root(
    search_from=__file__,
    indicator=".project-root",
    dotenv=True,
    pythonpath=True,
    cwd=True
)

Verify before relying

• Whether the package handles symlinks or unusual filesystem layouts reliably
• Performance characteristics when searching deeply nested directory hierarchies
• Compatibility with virtual environments and editable installs

Package facts

Evidence: pyrootutils-1.0.4-py3-none-any.whl

Tags

More Utilities packages