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.

Common errors

```
ModuleNotFoundError: No module named 'diagrams'
```
cause The 'diagrams' Python package is not installed in the environment where the code is being run, or the Python interpreter cannot find it.

fix Ensure the 'diagrams' package is installed using pip: `pip install diagrams`.
```
graphviz.backend.ExecutableNotFound: failed to execute ['dot', '-Tpng'], make sure the Graphviz executables are on your systems' PATH
```
cause The 'diagrams' library relies on the external Graphviz software to render diagrams, but the Graphviz executable ('dot') is either not installed on your system or its location is not included in your system's PATH environment variable.

fix Install Graphviz on your operating system (e.g., `brew install graphviz` on macOS, `sudo apt-get install graphviz` on Ubuntu/Debian, or download from graphviz.org for Windows) and ensure its 'bin' directory is added to your system's PATH. Restart your terminal or IDE after modifying the PATH.
```
pydot.InvocationException: GraphViz's executables not found
```
cause Similar to `ExecutableNotFound`, this error indicates that the `pydot` library (often used by `diagrams` or other graphing libraries) cannot locate the Graphviz executables, meaning Graphviz is either not installed or not in the system's PATH.

fix Install Graphviz on your operating system (e.g., `brew install graphviz` on macOS, `sudo apt-get install graphviz` on Ubuntu/Debian, or download from graphviz.org for Windows) and ensure its 'bin' directory is added to your system's PATH. Restart your terminal or IDE after modifying the PATH. Additionally, verify `pydot` is installed via `pip install pydot` or `conda install pydot`.

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 →