Diagrams
Python code that draws cloud architecture diagrams, rendered with Graphviz.
- Stars
- 42.8k
- Forks
- 2.7k
- Licence
- MIT
- Language
- Python
- Last update
- 4 days ago
- Type
- Library
What it is
Diagrams is a Python library where you describe a system architecture in code and it renders a diagram image. It includes icons for major cloud providers such as AWS, Azure, GCP and Kubernetes, plus on-premises, SaaS and programming nodes. Because the diagram is code, it can be tracked in version control and changed like any other source file. It does not touch real cloud resources or generate Terraform or CloudFormation.
- Draw a proposed system design before building it
- Document an existing cloud environment as a versioned diagram
- Generate architecture images for documentation pages
- Try diagrams in the online playground without installing anything
Great for
- Engineers who want to sketch a cloud architecture quickly without a drawing tool
- Teams that keep architecture docs in git and want diagrams to diff and review
- People documenting an existing cloud setup from code
- Users comfortable with basic Python
Not ideal for
- People who need to deploy or manage cloud resources, since it only draws diagrams and does not control infrastructure
- Anyone who wants a drag-and-drop visual editor, since diagrams are written in code
- Users who cannot install Graphviz or Python 3.9+
How to get it
- 1
Install with a package manager
You'll need: Python 3.9 or higher · Graphviz
Install with pip
pip install diagramsInstall with pipenv
pipenv install diagramsInstall with poetry
poetry add diagramsInstall Graphviz on macOS with Homebrew
brew install graphviz - 2
Run it
- Install Graphviz for your operating system
- Install the diagrams package with pip
- Write a Python script that defines a Diagram and its nodes
- Run the script to render the diagram image
- Or try the online playground to test without installing
- 3
Get the most out of it
- Use the online playground to search nodes and export PNG, SVG or JPEG before writing code
- Browse the node lists for AWS, Azure, GCP and Kubernetes in the docs to find the right icons
- Keep diagram scripts in your repository so architecture changes show up in code review
- Follow the guides in the documentation for layout and styling options
Downloads
Strengths
- Diagrams are plain Python code that can be versioned and reviewed
- Supports many providers and node types out of the box
- MIT licensed and actively maintained, with a browser playground for trying it
Trade-offs
- Rendering depends on Graphviz being installed separately
- Layout is determined automatically, so fine positioning control is limited
- Does not read live cloud state or generate infrastructure code
How it compares
| Project | Stars | Type | Level | Updated | Best for |
|---|---|---|---|---|---|
| diagrams (this) | 42.8k | Library | beginner | 4 days ago | Engineers who want to sketch a cloud architecture quickly without a drawing tool |
| mermaid | 91k | Dev tool | beginner | 4 days ago | Developers who want diagrams stored as text alongside their code and docs |
| drawio-skill | 10.5k | AI model / agent | intermediate | 5 days ago | Developers who want architecture diagrams generated from existing infrastructure or schema files |
| kratos | 26k | Library | intermediate | 4 days ago | Go developers building a set of backend services that talk over HTTP or gRPC |
| swift-composable-architecture | 15k | Library | intermediate | 9 days ago | Swift developers building SwiftUI or UIKit apps who want a consistent structure for features |
| CleanArchitecture | 18.5k | Framework | intermediate | 2 months ago | C# developers starting a new ASP.NET Core project who want a structured layout |
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.