Python Find Project Root Cookbook

Simple and short code examples to find the root directory of your project in different ways. This can be useful in projects where you are reading or writing data to directories inside your project directory. All examples return a pathlib.Path object.

To use, just copy and paste one of the examples into your project. Make any adjustments as needed or desired. These examples are all fairly straightforward and generally have no external dependencies. All code in this repository is licensed under the MIT No Attribution (MIT-0) License and can be used without attribution.

If for some reason you prefer to take on a dependency or to have a function resolve a bunch of criteria automagically, see these packages as alternatives: pyprojroot, rootpath

Cookbook

Table of contents:

• Find pyproject.toml file
• Find pyproject.toml file matching project name
• Find .git directory
• Find a specific file containing a specific value
• Read from environment variable

Find pyproject.toml file

pyproject.toml is a modern standard configuration file for packaging metadata and tools configuration. It's typically in the project root directory of Python projects.

from pathlib import Path


def proj_root_from_pyproject_toml() -> Path:
    """Find the nearest parent directory containing pyproject.toml."""
    current_dir = Path.cwd()
    while current_dir.parent != current_dir:
        if (current_dir / "pyproject.toml").exists():
            return current_dir
        current_dir = current_dir.parent
    raise RuntimeError("pyproject.toml not found in any parent directories.")

Find pyproject.toml file matching project name

If you're in a monorepo with multiple Python packages, you may want to find the specific intended pyproject.toml file by matching on its contents.

from pathlib import Path
import tomllib


def proj_root_from_pyproject_toml() -> Path:
    """Find the nearest parent directory containing pyproject.toml where the project
    name is 'my-project-name'."""
    project_name = "my-project-name"
    current_dir = Path.cwd()
    while current_dir.parent != current_dir:
        if (current_dir / "pyproject.toml").exists():
            with (current_dir / "pyproject.toml").open("rb") as f:
                pyproject = tomllib.load(f)
            if pyproject.get("project", {}).get("name") == project_name:
                return current_dir
        current_dir = current_dir.parent
    raise RuntimeError(
        f"pyproject.toml for '{project_name}' not found in any parent directories."
    )

Tip

tomllib was added to the Python standard library in 3.11. To support earlier versions of Python, use the tomli backport. You can use this dependency specifier:

tomli >= 1.1.0 ; python_version < "3.11"

and use this code to import it

import sys

if sys.version_info[:2] >= (3, 11):
    import tomllib
else:
    import tomli as tomllib

Find .git directory

If using Git as your version control system, there will be a .git directory in your project root.

from pathlib import Path


def proj_root_from_git() -> Path:
    """Find the nearest parent directory containing .git."""
    current_dir = Path.cwd()
    while current_dir.parent != current_dir:
        if (current_dir / ".git").exists():
            return current_dir
        current_dir = current_dir.parent
    raise RuntimeError(".git not found in any parent directories.")

Find a .here file

Popularized by R's here package, some project root detection tools support finding a file named .here.

from pathlib import Path


def proj_root_from_here_file() -> Path:
    """Find the nearest parent directory containing a file '.here'."""
    current_dir = Path.cwd()
    while current_dir.parent != current_dir:
        if (current_dir / ".here").exists():
            return current_dir
        current_dir = current_dir.parent
    raise RuntimeError("'.here' file not found in any parent directories.")

Read from environment variable

Environment variables are a good way specify configuration values that vary between running environments.

import os
from pathlib import Path


def proj_root_from_env_var() -> Path:
    """Get the project root directory from an environment variable. It must be an
    absolute path."""
    proj_root = os.environ.get("PROJ_ROOT")
    if not proj_root:
        raise RuntimeError("PROJ_ROOT environment variable is not set.")
    path = Path(proj_root)
    if not path.is_absolute():
        raise RuntimeError("PROJ_ROOT must be an absolute path.")
    return path