---
id: rootutils
version: "1.0.7"
license: MIT
license_treatment: permissive
maintenance: active
---

# rootutils — Simple package for easy project root setup

License: permissive · Maintenance: active · Downloads: 222.5K/mo

## What it is and what it does

Rootutils solves a common Python development friction point: ensuring that imports, file paths, and environment variables work consistently regardless of where a script is executed from. It searches up the directory tree for a marker file (like .git, setup.py, or .project-root) to identify your project root, then configures Python's path, working directory, and environment in a single call. The package wraps python-dotenv to load .env files automatically.

The typical workflow is a one-liner at the top of your script or notebook: `rootutils.setup_root(__file__, dotenv=True, pythonpath=True)`. This is especially useful in notebooks nested in subdirectories, where relative imports and file access would otherwise require fragile path manipulation. The package is small, actively maintained, and requires only Python 3.7+.

Use it for:

- Set up Jupyter notebooks in nested directories so they can import modules and access data relative to project root.
- Run Python scripts from any working directory without hardcoding absolute paths or managing PYTHONPATH manually.
- Load environment variables from .env automatically without explicit dotenv.load_dotenv() calls.
- Standardize file access across a project by always resolving paths relative to a marker file like .git.
- Configure CI/CD pipelines to run tests consistently regardless of the runner's working directory.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Finds your project root directory and configures Python path, working directory, and environment variables in one call, so scripts run consistently from anywhere.

Yes. Rootutils is a lightweight, actively maintained utility that solves a genuine pain point in Python development. Low install friction, permissive license, no known vulnerabilities, and a straightforward API make it a safe choice for projects that need reliable project-root discovery and path configuration.

## Install

pip install rootutils
uv add rootutils
poetry add rootutils

## Installing rootutils

Before you install: Low friction: pure Python wheel with a single runtime dependency (python-dotenv). Maintenance is active with recent commits and a modest but steady user base.

License in practice: MIT license is permissive; you can use, modify, and distribute this package freely with minimal restrictions.

Quickstart:

import rootutils

root = rootutils.setup_root(__file__, dotenv=True, pythonpath=True, cwd=False)

# Now import modules relative to root and access files via root / "path"

Requires Python 3.7.0 or later; python-dotenv must be installed as a runtime dependency.

Verify before relying:

- Whether the package correctly handles edge cases (symlinks, monorepos, nested .git directories).
- Performance impact of recursive directory searches in large project hierarchies.
- Compatibility with virtual environments and containerized workflows.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 222.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

project root finder, pythonpath setup, working directory management, relative imports from project root, environment variable loader, .env file loader, python path configuration, path-management, project-setup

[View on SkillFed](https://skillfed.io/packages/rootutils) · [View on PyPI](https://pypi.org/project/rootutils/)