{"id":26361374,"url":"https://github.com/jayqi/python-find-project-root-cookbook","last_synced_at":"2025-03-16T17:37:57.808Z","repository":{"id":281294099,"uuid":"944841930","full_name":"jayqi/python-find-project-root-cookbook","owner":"jayqi","description":"Short code examples to find the root directory of your project","archived":false,"fork":false,"pushed_at":"2025-03-08T04:43:28.000Z","size":0,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-08T05:24:42.999Z","etag":null,"topics":["pathlib","project-root","project-root-path","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit-0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jayqi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-08T04:28:19.000Z","updated_at":"2025-03-08T04:45:00.000Z","dependencies_parsed_at":"2025-03-08T05:34:49.801Z","dependency_job_id":null,"html_url":"https://github.com/jayqi/python-find-project-root-cookbook","commit_stats":null,"previous_names":["jayqi/python-find-project-root-cookbook"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayqi%2Fpython-find-project-root-cookbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayqi%2Fpython-find-project-root-cookbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayqi%2Fpython-find-project-root-cookbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayqi%2Fpython-find-project-root-cookbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jayqi","download_url":"https://codeload.github.com/jayqi/python-find-project-root-cookbook/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243909108,"owners_count":20367532,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pathlib","project-root","project-root-path","python"],"created_at":"2025-03-16T17:37:10.239Z","updated_at":"2025-03-16T17:37:57.790Z","avatar_url":"https://github.com/jayqi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python Find Project Root Cookbook\n\n[![tests](https://github.com/jayqi/reprexlite/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/jayqi/reprexlite/actions/workflows/tests.yml?query=workflow%3Atests+branch%3Amain)\n\nSimple 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`](https://docs.python.org/3/library/pathlib.html) object.\n\nTo 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](./LICENSE) and can be used without attribution.\n\nIf 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](https://github.com/chendaniely/pyprojroot), [rootpath](https://github.com/grimen/python-rootpath)\n\n## Cookbook\n\nTable of contents:\n\n- [Find pyproject.toml file](#find-pyprojecttoml-file)\n- [Find pyproject.toml file matching project name](#find-pyprojecttoml-file-matching-project-name)\n- [Find .git directory](#find-git-directory)\n- [Find a specific file containing a specific value](#find-a-specific-file-containing-a-specific-value)\n- [Read from environment variable](#read-from-environment-variable)\n\n### Find pyproject.toml file\n\n[`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-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.\n\n```python\nfrom pathlib import Path\n\n\ndef proj_root_from_pyproject_toml() -\u003e Path:\n    \"\"\"Find the nearest parent directory containing pyproject.toml.\"\"\"\n    current_dir = Path.cwd()\n    while current_dir.parent != current_dir:\n        if (current_dir / \"pyproject.toml\").exists():\n            return current_dir\n        current_dir = current_dir.parent\n    raise RuntimeError(\"pyproject.toml not found in any parent directories.\")\n```\n\n\n### Find pyproject.toml file matching project name\n\nIf 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.\n\n```python\nfrom pathlib import Path\nimport tomllib\n\n\ndef proj_root_from_pyproject_toml() -\u003e Path:\n    \"\"\"Find the nearest parent directory containing pyproject.toml where the project\n    name is 'my-project-name'.\"\"\"\n    project_name = \"my-project-name\"\n    current_dir = Path.cwd()\n    while current_dir.parent != current_dir:\n        if (current_dir / \"pyproject.toml\").exists():\n            with (current_dir / \"pyproject.toml\").open(\"rb\") as f:\n                pyproject = tomllib.load(f)\n            if pyproject.get(\"project\", {}).get(\"name\") == project_name:\n                return current_dir\n        current_dir = current_dir.parent\n    raise RuntimeError(\n        f\"pyproject.toml for '{project_name}' not found in any parent directories.\"\n    )\n```\n\n\n\u003e [!TIP]\n\u003e [tomllib](https://docs.python.org/3/library/tomllib.html) was added to the Python standard library in 3.11. To support earlier versions of Python, use the [tomli](https://github.com/hukkin/tomli) backport. You can use this dependency specifier:\n\u003e ```\n\u003e tomli \u003e= 1.1.0 ; python_version \u003c \"3.11\"\n\u003e ```\n\u003e and use this code to import it\n\u003e ```python\n\u003e import sys\n\u003e\n\u003e if sys.version_info[:2] \u003e= (3, 11):\n\u003e     import tomllib\n\u003e else:\n\u003e     import tomli as tomllib\n\u003e\n\u003e ```\n\n### Find .git directory\n\nIf using Git as your version control system, there will be a `.git` directory in your project root.\n\n```python\nfrom pathlib import Path\n\n\ndef proj_root_from_git() -\u003e Path:\n    \"\"\"Find the nearest parent directory containing .git.\"\"\"\n    current_dir = Path.cwd()\n    while current_dir.parent != current_dir:\n        if (current_dir / \".git\").exists():\n            return current_dir\n        current_dir = current_dir.parent\n    raise RuntimeError(\".git not found in any parent directories.\")\n```\n\n\n### Find a .here file\n\nPopularized by R's [here](https://here.r-lib.org/) package, some project root detection tools support finding a file named `.here`.\n\n```python\nfrom pathlib import Path\n\n\ndef proj_root_from_here_file() -\u003e Path:\n    \"\"\"Find the nearest parent directory containing a file '.here'.\"\"\"\n    current_dir = Path.cwd()\n    while current_dir.parent != current_dir:\n        if (current_dir / \".here\").exists():\n            return current_dir\n        current_dir = current_dir.parent\n    raise RuntimeError(\"'.here' file not found in any parent directories.\")\n```\n\n\n### Read from environment variable\n\nEnvironment variables are a good way specify configuration values that vary between running environments.\n\n```python\nimport os\nfrom pathlib import Path\n\n\ndef proj_root_from_env_var() -\u003e Path:\n    \"\"\"Get the project root directory from an environment variable. It must be an\n    absolute path.\"\"\"\n    proj_root = os.environ.get(\"PROJ_ROOT\")\n    if not proj_root:\n        raise RuntimeError(\"PROJ_ROOT environment variable is not set.\")\n    path = Path(proj_root)\n    if not path.is_absolute():\n        raise RuntimeError(\"PROJ_ROOT must be an absolute path.\")\n    return path\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjayqi%2Fpython-find-project-root-cookbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjayqi%2Fpython-find-project-root-cookbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjayqi%2Fpython-find-project-root-cookbook/lists"}