{"id":6194,"library":"rootutils","title":"rootutils","description":"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.","status":"active","version":"1.0.7","language":"en","source_language":"en","source_url":"https://github.com/ashleve/rootutils","tags":["project setup","path management","root directory","imports"],"install":[{"cmd":"pip install rootutils","lang":"bash","label":"Install current version"},{"cmd":"pip install pyrootutils # For versions < 1.0.5","lang":"bash","label":"Install legacy package name"}],"dependencies":[],"imports":[{"note":"The library was renamed from `pyrootutils` to `rootutils` in v1.0.5. Old imports will fail for versions >= 1.0.5.","wrong":"from pyrootutils import find_root","symbol":"find_root","correct":"from rootutils import find_root"},{"note":"The library was renamed from `pyrootutils` to `rootutils` in v1.0.5. Old imports will fail for versions >= 1.0.5.","wrong":"from pyrootutils import setup_root","symbol":"setup_root","correct":"from rootutils import setup_root"},{"note":"`autosetup` was introduced in v1.0.6 and is also affected by the `pyrootutils` to `rootutils` rename from v1.0.5.","wrong":"from pyrootutils import autosetup","symbol":"autosetup","correct":"from rootutils import autosetup"}],"quickstart":{"code":"import rootutils\nimport os\nimport sys\n\n# Simulate a project root by creating an indicator file in the current directory.\n# In a real project, you would call this from a subdirectory.\nindicator_file = \".project-root\"\nwith open(indicator_file, \"w\") as f:\n    f.write(\"\")\n\ntry:\n    # Find the project root (current directory in this simulation)\n    # and add it to sys.path for simplified imports.\n    root_dir = rootutils.autosetup(\n        indicator_file=indicator_file, # The file to look for\n        project_dir=os.getcwd(),     # Start search from current directory\n        add_to_pythonpath=True       # Explicitly ensure it's added\n    )\n\n    print(f\"Project root found: {root_dir}\")\n    print(f\"Does sys.path contain project root? {str(root_dir) in sys.path}\")\n\n    # Example: In a real project, if you have a 'config' directory at the root,\n    # you could now do: 'from config import settings'\n    # without complex relative imports.\n\nfinally:\n    # Clean up the simulated indicator file\n    if os.path.exists(indicator_file):\n        os.remove(indicator_file)\n","lang":"python","description":"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."},"warnings":[{"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`.","message":"The 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.","severity":"breaking","affected_versions":">=1.0.5"},{"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`.","message":"`rootutils.find_root()` only returns the path to the project root and does NOT modify `sys.path` by default.","severity":"gotcha","affected_versions":"All"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}