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.
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
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.063s · 18MB
glibcpy 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.
The library was renamed from `pyrootutils` to `rootutils` in v1.0.5. Old imports will fail for versions >= 1.0.5.
from rootutils import find_root
The library was renamed from `pyrootutils` to `rootutils` in v1.0.5. Old imports will fail for versions >= 1.0.5.
from rootutils import setup_root
`autosetup` was introduced in v1.0.6 and is also affected by the `pyrootutils` to `rootutils` rename from v1.0.5.
from rootutils import autosetup
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)
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.