---
id: pytest-archon
version: "0.0.7"
license: Apache Software License
license_treatment: permissive
maintenance: aging
---

# pytest-archon — Rule your architecture like a real developer

License: permissive · Maintenance: aging · Downloads: 83.9K/mo

## What it is and what it does

Pytest-archon is a pytest plugin that lets you write tests to enforce architectural rules in your Python codebase. Instead of relying on informal conventions, you define explicit boundaries—specifying which modules can import from which others—and verify them as part of your test suite. It catches circular dependencies, prevents unintended coupling, and makes your project structure explicit for new team members.

You write rules using a fluent API that matches module patterns (via fnmatch or regex), excludes specific modules, and specifies allowed or forbidden imports. The check method can inspect toplevel imports only, skip TYPE_CHECKING blocks, or include transitive dependencies, giving you fine-grained control over what gets validated. Rules are tied directly to your codebase, so they stay in sync with actual application structure.

Use it for:

- Enforce that a domain model layer has no dependencies on other submodules, keeping it reusable and decoupled.
- Verify that utility or common modules are actually used by multiple parts of the codebase, preventing dead code.
- Prevent circular imports between major architectural layers (e.g., controllers cannot import from views).
- Document and test the intended module hierarchy for new team members through executable rules.
- Catch unintended coupling between components during development before it becomes entrenched.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Pytest-archon lets you define and test architectural boundaries in Python projects by specifying which modules can import from which others, catching circular dependencies and enforcing structure through test rules.

Yes, if you want to enforce architectural boundaries in a growing Python project. The low install friction, permissive license, and stable API make it straightforward to adopt. The aging maintenance status (329 days since last release) is a minor concern but not a blocker—the repository is active and the package is marked Production/Stable. Use it when you need testable, explicit rules about module dependencies rather than informal conventions.

## Install

pip install pytest-archon
uv add pytest-archon
poetry add pytest-archon

## Installing pytest-archon

Before you install: Low friction install with a single runtime dependency on pytest. Maintenance status is aging—last release was 329 days ago—but the repository is active and not archived, with a stable development status classifier.

License in practice: Licensed under Apache Software License (permissive), so you can use, modify, and distribute it freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install pytest-archon

from pytest_archon import archrule

def test_rule_basic():
    (
        archrule("name", comment="some comment")
        .match("pytest_archon.col*")
        .exclude("pytest_archon.colgate")
        .should_not_import("pytest_archon.import_finder")
        .should_import("pytest_archon.core*")
        .check("pytest_archon")
    )

Requires Python 3.8 or later; pytest must be installed.

Verify before relying:

- Whether the aging maintenance status (329 days since last release) affects stability or security for new Python versions.
- Performance characteristics when checking large codebases or deeply nested dependency graphs.

## Package facts

- License: Apache Software License (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 83.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

architecture testing python, forbidden dependencies enforcement, circular dependency detection, module import rules, code structure validation, pytest architecture rules, dependency boundaries testing, architecture-testing, dependency-management

[View on SkillFed](https://skillfed.io/packages/pytest-archon) · [View on PyPI](https://pypi.org/project/pytest-archon/)