A Python DSL for C4 model diagrams.

c4-diagrams

c4-diagrams is a Python DSL for defining C4 model architecture diagrams as code.

The package provides first-class abstractions for C4 entities — people, systems, containers, components, boundaries, and relationships — allowing you to describe software architecture in Python and render it into multiple diagram formats.

Features

Declarative Python DSL for C4 modeling
First-class C4 entities and relationships
Multiple rendering backends
Suitable for documentation, ADRs, and architecture reviews
Portable core DSL for the common C4 subset, with backend-specific features available through contrib extensions

Rendering backends

Currently supported backends:

PlantUML
- local rendering via plantuml CLI or plantuml.jar
- remote rendering via PlantUML server
Mermaid
- local rendering via Mermaid CLI
- Mermaid’s C4 diagram support is currently experimental
D2
- local rendering via D2 CLI
Structurizr - WIP

Getting started

c4-diagrams requires Python 3.10 or higher.

pip install c4-diagrams

Example

Here’s an example of a system context diagram defined in Python:

# diagram.py
from c4 import (
    EnterpriseBoundary,
    Person,
    System,
    SystemContextDiagram,
    SystemExt,
)
from c4.contrib.plantuml import RelDown, RelRight


with SystemContextDiagram("Acme Shop Platform") as diagram:
    user = Person(
        "Customer",
        "A registered customer who browses products and places orders.",
    )

    with EnterpriseBoundary("Acme Corp"):
        web_app = System(
            "Web Application",
            "Customer-facing website for browsing products and placing orders.",
        )

        api_backend = System(
            "Backend API",
            "Handles authentication, order processing, and business logic.",
        )

    email_provider = SystemExt(
        "Email Provider",
        "Delivers transactional emails.",
    )

    user >> RelRight("Uses") >> web_app
    web_app >> RelRight("Calls API") >> api_backend
    api_backend >> RelDown("Sends emails via") >> email_provider

To export the diagram to a rendered artifact, run:

c4 export diagram.py > diagram.png

This generates the diagram below:

readme-diagram

diagram.png

For details (renderers, diagram types, API), see the documentation.

Project Links

License

MIT LICENSE

This project bundles files from the C4-PlantUML project. C4-PlantUML is licensed under the MIT License.

Contribution

Contribution guidelines for this project

Repository initiated with fpgmaas/cookiecutter-uv.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

c4_diagrams-0.7.1.tar.gz (151.4 kB view details)

Uploaded Jul 6, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

c4_diagrams-0.7.1-py3-none-any.whl (195.1 kB view details)

Uploaded Jul 6, 2026 Python 3

File details

Details for the file c4_diagrams-0.7.1.tar.gz.

File metadata

Download URL: c4_diagrams-0.7.1.tar.gz
Upload date: Jul 6, 2026
Size: 151.4 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for c4_diagrams-0.7.1.tar.gz
Algorithm	Hash digest
SHA256	`25c47bd64e4d89cee391cccd504974edde20fe3941304345c94bf3832faa0cec`
MD5	`7535344210b6fd6c4899da64803d550e`
BLAKE2b-256	`b61cc69d6ad6c0925a6b8a0d14fcad72872071b560328852beb3490886dc4806`

See more details on using hashes here.

Provenance

The following attestation bundles were made for c4_diagrams-0.7.1.tar.gz:

Publisher: on-release-main.yml on sidorov-as/c4-diagrams

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: c4_diagrams-0.7.1.tar.gz
- Subject digest: 25c47bd64e4d89cee391cccd504974edde20fe3941304345c94bf3832faa0cec
- Sigstore transparency entry: 2084816075
- Sigstore integration time: Jul 6, 2026
Source repository:
- Permalink: sidorov-as/c4-diagrams@a445193ddc529d967bd5fc7bcc5e3dc65e0cf8c5
- Branch / Tag: refs/tags/0.7.1
- Owner: https://github.com/sidorov-as
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: on-release-main.yml@a445193ddc529d967bd5fc7bcc5e3dc65e0cf8c5
- Trigger Event: release