{"id":4273,"library":"tach","title":"Tach - Python Modular Architecture Tool","description":"Tach is a Python CLI tool (implemented in Rust) designed to enforce modular design and control dependencies between Python modules within a project. It enables developers to define explicit module boundaries, prevent deep coupling, enforce public interfaces, and detect circular dependencies. Actively maintained with frequent releases, the current version is 0.34.1, requiring Python 3.9 or higher.","status":"active","version":"0.34.1","language":"en","source_language":"en","source_url":"https://github.com/tach-org/tach","tags":["architecture","modular","cli","static analysis","dependencies","pytest","linter"],"install":[{"cmd":"pip install tach","lang":"bash","label":"Install `tach`"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","version":">=3.9"},{"reason":"Core configuration parsing.","package":"pyyaml","version":"~=6.0"},{"reason":"Core configuration parsing.","package":"tomli","version":">=1.2.2"},{"reason":"Core configuration writing.","package":"tomli-w","version":"~=1.0"},{"reason":"For rich terminal output.","package":"rich","version":">=13.0"},{"reason":"For interactive CLI features.","package":"prompt-toolkit","version":"~=3.0"},{"reason":"For Git repository interactions (e.g., --base, --head for 'tach test').","package":"GitPython","version":"~=3.1"},{"reason":"For dependency graph analysis.","package":"networkx","version":">=2.6,<4.0"},{"reason":"For visualizing dependency graphs ('tach show').","package":"pydot","version":">=2,<5"},{"reason":"Required for 'tach test' command and pytest plugin integration.","package":"pytest","optional":true}],"imports":[],"quickstart":{"code":"import os\nimport textwrap\n\n# Create a dummy project structure\nos.makedirs(\"my_project/src/app\", exist_ok=True)\nos.makedirs(\"my_project/src/utils\", exist_ok=True)\n\nwith open(\"my_project/src/app/__init__.py\", \"w\") as f:\n    f.write(\"\")\nwith open(\"my_project/src/app/main.py\", \"w\") as f:\n    f.write(\"from src.utils.helpers import greet\\n\\ndef run():\\n    print(greet('World'))\\n\")\nwith open(\"my_project/src/utils/__init__.py\", \"w\") as f:\n    f.write(\"\"\n)\nwith open(\"my_project/src/utils/helpers.py\", \"w\") as f:\n    f.write(\"def greet(name):\\n    return f'Hello, {name}'\\n\")\n\ntach_toml_content = textwrap.dedent(\"\"\"\n    [[layers]]\n    name = \"app\"\n    path = \"src/app\"\n    dependencies = [\"utils\"]\n\n    [[layers]]\n    name = \"utils\"\n    path = \"src/utils\"\n    dependencies = []\n\"\"\")\n\nwith open(\"my_project/tach.toml\", \"w\") as f:\n    f.write(tach_toml_content)\n\nprint(\"Project structure and tach.toml created in 'my_project' directory.\")\nprint(\"Navigate to 'my_project' and run 'tach check' to validate boundaries.\")","lang":"python","description":"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`."},"warnings":[{"fix":"Upgrade Python to >=3.9 or downgrade `tach` to a version supporting Python 3.8.","message":"Tach 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.","severity":"breaking","affected_versions":"<0.34.0"},{"fix":"Upgrade 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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.33.0, <0.34.1"},{"fix":"Be 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.","message":"Tach 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review 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`.","message":"From `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.","severity":"gotcha","affected_versions":">=0.33.1"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}