Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
To get started, first initialize a `tach.toml` file in your project root, which can be done interactively using `tach init` or by creating it manually. You define modules and their allowed dependencies (or layers) within this file. The `tach mod` command provides an interactive editor for defining module boundaries. After defining your boundaries, run `tach sync` to automatically populate dependency rules based on existing imports, then use `tach check` to validate your architecture. This example creates a basic project structure with a `tach.toml` to illustrate module `app` depending on `utils`.
import os
import textwrap
# Create a dummy project structure
os.makedirs("my_project/src/app", exist_ok=True)
os.makedirs("my_project/src/utils", exist_ok=True)
with open("my_project/src/app/__init__.py", "w") as f:
f.write("")
with open("my_project/src/app/main.py", "w") as f:
f.write("from src.utils.helpers import greet\n\ndef run():\n print(greet('World'))\n")
with open("my_project/src/utils/__init__.py", "w") as f:
f.write(""
)
with open("my_project/src/utils/helpers.py", "w") as f:
f.write("def greet(name):\n return f'Hello, {name}'\n")
tach_toml_content = textwrap.dedent("""
[[layers]]
name = "app"
path = "src/app"
dependencies = ["utils"]
[[layers]]
name = "utils"
path = "src/utils"
dependencies = []
""")
with open("my_project/tach.toml", "w") as f:
f.write(tach_toml_content)
print("Project structure and tach.toml created in 'my_project' directory.")
print("Navigate to 'my_project' and run 'tach check' to validate boundaries.")
tach --version
Debug
Known issues
breakingTach dropped official support for Python 3.8 in version `0.34.0`. Users on older Python versions must use `tach < 0.34.0` or upgrade their Python environment.fixUpgrade Python to >=3.9 or downgrade `tach` to a version supporting Python 3.8.
affects: <0.34.0
gotchaThe `tach test` command and its pytest plugin have undergone several changes and fixes, particularly around auto-loading and default behaviors since `v0.33.0`. Earlier versions might have experienced issues like the plugin being registered twice, leading to `ValueError`, or incorrect test skipping. Ensure you are on the latest `tach` version for the most stable pytest integration.fixUpgrade to `tach >= 0.34.1` for pytest plugin stability. Consult the documentation for any changes in pytest plugin configuration or command-line flags if upgrading from significantly older versions.
affects: >=0.33.0, <0.34.1
gotchaTach performs static analysis of your codebase by analyzing the Abstract Syntax Tree (AST). This means it will not detect or enforce rules for dynamic imports (e.g., those using `importlib`), as these are only resolved at runtime.fixBe aware that dynamic import patterns will bypass Tach's enforcement. Design your modular architecture to primarily use static imports where boundaries need to be enforced.
affects: All versions
gotchaFrom `v0.33.1`, a `layers_explicit_depends_on` flag was added to `tach.toml`. If set to `true`, modules in higher layers must explicitly declare dependencies on lower layers, even if implicitly allowed by the layer hierarchy. By default, higher layers can depend on lower layers without explicit declaration.fixReview your `tach.toml` if you are using layers and wish for stricter explicit dependency declarations between them. Set `layers_explicit_depends_on = true` under `[config]` in your `tach.toml`.
affects: >=0.33.1
Errors
Common errors & fixes
tach: command not found
The 'tach' executable is not in your system's PATH, or the installation via `pip` was unsuccessful.
fixEnsure `pip install tach` completed without errors and that the directory where pip installs executables (e.g., `~/.local/bin` on Linux/macOS, `Scripts` in Python install dir on Windows) is included in your system's PATH. You may need to restart your terminal.
error: Failed to parse configuration file at 'pyproject.toml'
The `pyproject.toml` file contains syntax errors (e.g., malformed TOML) or structural issues that prevent `tach` from reading its configuration.
fixCarefully review your `pyproject.toml` for syntax errors, missing quotes, incorrect indentation, or invalid TOML structure within the `[tool.tach]` section. Use a TOML linter or editor with TOML support.
error: No [tool.tach] section found in pyproject.toml.
The `pyproject.toml` file exists, but it either lacks a `[tool.tach]` section or it's improperly formatted, preventing `tach` from finding its specific configuration.
fixAdd or correct the `[tool.tach]` section in your `pyproject.toml` file, ensuring it's a top-level table and contains valid `tach` configuration keys as specified in the documentation.
error: Path 'src' in 'root_paths' does not exist.
The `root_paths` defined in your `pyproject.toml` specify directories that do not exist relative to where `tach` is being run, or they point to incorrect locations for your source code.
fixVerify that the paths listed under `[tool.tach].root_paths` in `pyproject.toml` accurately reflect the locations of your source code directories, relative to the project root where you execute `tach`. Ensure these directories actually exist.
Error: Failed to parse config file: Missing required field "root_module".
Your `pyproject.toml` or `tach.toml` configuration is missing the mandatory `root_module` field, which specifies the base module of your project.
fixAdd the `root_module` field under `[tool.tach]` in your `pyproject.toml` (or `[config]` in `tach.toml`) specifying the top-level module of your project, e.g., `root_module = "my_project_name"`.
Upgrade
Version history
0.34.1latest on PyPI · released Apr 3, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.
pyyamlrequiredCore configuration parsing.
tomlirequiredCore configuration parsing.
tomli-wrequiredCore configuration writing.
richrequiredFor rich terminal output.
prompt-toolkitrequiredFor interactive CLI features.
GitPythonrequiredFor Git repository interactions (e.g., --base, --head for 'tach test').
networkxrequiredFor dependency graph analysis.
pydotrequiredFor visualizing dependency graphs ('tach show').
pytestoptionalRequired for 'tach test' command and pytest plugin integration.