rootutils

library1.0.7pypypi✓ verified 87d ago

rootutils (formerly pyrootutils) is a Python library designed for simple and robust project root setup. It helps locate the project root directory using an indicator file and can optionally add it to `sys.path` for simplified imports. The library is currently at version 1.0.7 and maintains a moderately active release cadence, typically releasing minor updates or bug fixes every few months.

devops data

pip install rootutils

github ↗package ↗

INSTALL

IMPORT

SIG · ROOTUTILS

rootutils

devopspythonv1.0.7

Install

1.6s avg

Import

60ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.7 · 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.10–3.940 runs

installs and imports cleanly · install 0.0s · import 0.063s · 18MB

glibc

py 3.10–3.940 runs

installs and imports cleanly · install 1.6s · import 0.057s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

find_root

✓ from rootutils import find_root

✗ from pyrootutils import find_root

The library was renamed from `pyrootutils` to `rootutils` in v1.0.5. Old imports will fail for versions >= 1.0.5.

setup_root

✓ from rootutils import setup_root

✗ from pyrootutils import setup_root

The library was renamed from `pyrootutils` to `rootutils` in v1.0.5. Old imports will fail for versions >= 1.0.5.

autosetup

✓ from rootutils import autosetup

✗ from pyrootutils import autosetup

`autosetup` was introduced in v1.0.6 and is also affected by the `pyrootutils` to `rootutils` rename from v1.0.5.

This example demonstrates how to use `rootutils.autosetup()` to find the project root (indicated by `.project-root`) and add it to `sys.path`. This enables direct imports of modules located within the project root, simplifying project structure management. The example simulates a project root by creating a temporary indicator file.

import rootutils import os import sys # Simulate a project root by creating an indicator file in the current directory. # In a real project, you would call this from a subdirectory. indicator_file = ".project-root" with open(indicator_file, "w") as f: f.write("") try: # Find the project root (current directory in this simulation) # and add it to sys.path for simplified imports. root_dir = rootutils.autosetup( indicator_file=indicator_file, # The file to look for project_dir=os.getcwd(), # Start search from current directory add_to_pythonpath=True # Explicitly ensure it's added ) print(f"Project root found: {root_dir}") print(f"Does sys.path contain project root? {str(root_dir) in sys.path}") # Example: In a real project, if you have a 'config' directory at the root, # you could now do: 'from config import settings' # without complex relative imports. finally: # Clean up the simulated indicator file if os.path.exists(indicator_file): os.remove(indicator_file)

Debug

Known issues

breakingThe library was officially renamed from `pyrootutils` to `rootutils` starting from version 1.0.5. This affects both the PyPI package name and all import statements.

fix

Update your `pip install` commands from `pyrootutils` to `rootutils`. Change all `import pyrootutils` statements to `import rootutils` throughout your codebase. If you need to maintain compatibility with older versions, consider conditional imports or pinning your dependency to `<1.0.5`.

affects: >=1.0.5

gotcha`rootutils.find_root()` only returns the path to the project root and does NOT modify `sys.path` by default.

fix

If you intend to make modules at the detected root importable, use `rootutils.setup_root(add_to_pythonpath=True)` or, more conveniently, `rootutils.autosetup()`. `autosetup()` is generally the recommended method as it combines finding the root with adding it to `sys.path`.

affects: All

gotchaThe library relies on an `indicator_file` (e.g., `.project-root`) to identify the project root. If this file is missing or `project_dir` is incorrectly specified, functions like `find_root` or `autosetup` will fail to locate the root.

fix

Ensure that an `indicator_file` (e.g., an empty `.project-root` file or `pyproject.toml`) exists in your actual project's root directory. If calling from an unusual location, explicitly set the `project_dir` argument to specify the starting point for the root search.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pyrootutils'

The library was renamed from `pyrootutils` to `rootutils`. Existing code trying to import `pyrootutils` will fail if only `rootutils` is installed.

fix

Update all occurrences of `import pyrootutils` to `import rootutils` in your codebase.

AttributeError: 'NoneType' object has no attribute 'joinpath'

`rootutils.setup_root()` failed to find the project root (e.g., `.project-root` file or `.git` directory) and returned `None`, but the code attempted to use the `None` object as if it were a `Path` object.

fix

Ensure the indicator file (e.g., `.project-root`, `.git` directory, `pyproject.toml`) exists in the desired project root. Always check the return value of `rootutils.setup_root()` for `None` before attempting to use it.

ERROR: Could not find a version that satisfies the requirement pyrootutils

The `pyrootutils` package has been deprecated and removed from PyPI. Users should install and use the renamed `rootutils` package instead.

fix

Replace `pip install pyrootutils` with `pip install rootutils` in your terminal or `requirements.txt`.

Upgrade

Version history

1.0.7latest on PyPI · released May 19, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ashleve/rootutils ↗

packagehttps://pypi.org/project/rootutils/ ↗