Python diagrams library alternative: when the .py file becomes the thing that rots

Four properties explain the adoption. Diagrams are code, so they diff, review, and version like everything else. The node catalog is wide: AWS, Azure, Google Cloud, IBM, Oracle Cloud, Alibaba Cloud, DigitalOcean, OpenStack, Firebase, Elastic, Kubernetes, on-premise, SaaS, programming frameworks, and a C4 set, all with official icons, so the picture looks like the deck it will end up in. Cluster blocks give you grouping without fighting a layout engine. And it costs nothing.

For prototyping, the loop is genuinely fast: sketch a topology in twenty lines, render, adjust, paste into an RFC. That is the use case the project states for itself, and pages that criticize the library for not being a documentation platform are criticizing the wrong tool.

Graphviz. The project states it plainly: it renders through Graphviz, so Graphviz has to be installed to use diagrams at all, on top of Python 3.9 or higher. Every machine that regenerates the picture needs both, CI runners and the laptop of whoever inherits the repo included. It is a small dependency that becomes a small ritual, and small rituals are the ones that stop happening.

Layout. Because the layout comes from Graphviz, controlling it means learning graph attributes, ranks, and invisible edges. Teams end up with a file where half the lines exist to make the picture come out straight, which makes the file harder to keep truthful.

The second source of truth. This is the one that matters. The .py file is not the infrastructure; it is a hand-written claim about the infrastructure that happens to be written in Python. Terraform can add a Redis cluster, a Helm chart can add a sidecar, and the diagram script stays green because it never looked. Diagram-as-code gives you a versioned history of the claim, not a check on the claim.

Written out as the sequence it actually is, the cost is easier to judge. Four of the five steps below are automatable. The one that is not is the one that fails.

# keeping a diagrams.py picture current, in full
brew install graphviz               # or apt-get install graphviz, on every machine
pip install diagrams                # Python 3.9 or higher
python architecture.py              # writes architecture.png
git add architecture.py architecture.png
git commit -m "docs: redraw after the redis cache landed"

# the step nothing schedules and nothing enforces:
# noticing that the redis cache landed at all

Datadef connects to the repository read-only on GitHub, GitLab, or Azure DevOps, reads the architecture-dense files (infrastructure as code, containers and orchestration, schemas and dbt models, API specs, CI pipelines, manifests), and generates the diagram plus an architecture.md. A daily sync regenerates both when the code moves, and you can refresh from the app or from a coding agent over MCP.

The icons carry over. The catalog holds more than 2000 marks, among them 438 AWS, 624 Azure, and 226 Google Cloud, so an S3 bucket looks like S3 and a dbt model looks like dbt, which is what made the Python library pleasant in the first place. A type the catalog does not recognise gets a neutral mark rather than a plausible wrong logo. The canvas is editable when the generated result needs a human touch, and exports as PNG or JPEG.

Regeneration is not a fresh drawing every morning either. Each sync hashes what actually feeds the diagram, so a commit that only touched a README, a test, or a comment leaves that hash unchanged and nothing is redrawn. When the structure did change, the previous ids, labels, and zones are handed back to the generator with instructions to reuse everything that still exists, and any node someone dragged keeps its coordinates. A one-resource change reads as a one-node change, which is a property a committed PNG never had.

The distribution model is different too. Rather than committing a rendered image next to the script, you embed a live image in the README, and the picture in the README is the current one by default.

For a proposed architecture that does not exist yet, there is nothing to derive from, and a twenty-line Python file remains the fastest path from idea to picture. The same goes for teaching material and for diagrams that need to say something the code does not contain, like a migration plan in three phases.

The rule of thumb: if the diagram describes something that exists in a repository, generate it. If it describes something that does not exist yet, draw it, from Python or from a prompt.

• Datadef compared with Mermaid
• Datadef compared with PlantUML
• The limits of docs-as-code diagrams
• Repo to diagram: repository sync