Diagrams

0.25.1 · active · verified Thu Apr 09

Diagrams is a Python library that allows users to draw cloud system architectures and other technical diagrams as code. It leverages Graphviz to render visual representations, enabling version-controlled, reproducible, and dynamic documentation for multi-cloud deployments (AWS, Azure, GCP, Kubernetes, etc.), on-premise solutions, and more. Currently at version 0.25.1, the library maintains an active release cadence with frequent updates adding new icons and features.

Warnings

gotcha The `diagrams` Python package requires the Graphviz system-level tool to be installed on your operating system. Without Graphviz, diagrams cannot be rendered, and you will encounter errors. This is a common oversight.
Fix: Install Graphviz according to your OS (e.g., `brew install graphviz` on macOS, `sudo apt-get install graphviz` on Debian/Ubuntu, download installer for Windows). Ensure the `dot` executable is in your system's PATH.
gotcha In version 0.25.1, the `pre-commit` development dependency was incorrectly included as a runtime dependency in the PyPI package. This means `pre-commit` and its transitive dependencies will be installed for all users of the library, increasing installation size and potentially causing conflicts.
Fix: While `diagrams` itself will still function, be aware of the unnecessary dependencies. This issue is likely to be addressed in a future patch release. For production environments, consider pinning to a version prior to 0.25.1 or waiting for a fix, if this is a concern.
breaking Diagrams requires Python 3.9 or higher. Using it with older Python versions will result in compatibility errors.
Fix: Ensure your environment uses Python 3.9 or a newer compatible version.

Install

pip install diagrams Install Python package
brew install graphviz Install Graphviz (macOS Homebrew)
sudo apt-get install graphviz Install Graphviz (Debian/Ubuntu)
choco install graphviz Install Graphviz (Windows Chocolatey)

Imports

Diagram
```
from diagrams import Diagram
```
EC2
```
from diagrams.aws.compute import EC2
```
Node types are imported from their respective cloud/provider sub-modules (e.g., `diagrams.aws`, `diagrams.azure`, `diagrams.gcp`).

Quickstart

This example generates a simple AWS web application diagram, saving it as 'simple_web_app.png' in the current directory without automatically opening the image.

from diagrams import Diagram
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.storage import S3

with Diagram("Simple Web Application", show=False, filename="simple_web_app"):
    web_server = EC2("Web Server")
    database = RDS("Database")
    static_storage = S3("Static Content")

    web_server >> database
    web_server >> static_storage

view raw JSON →