diagrams

library0.25.1pypypi✓ verified 27d ago

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.

devops aws gcp azure

pip install diagrams

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DIAGRAMS

diagrams

devopspythonv0.25.1

Install

3.9s avg

Import

109ms

Disk

74MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.25.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.112s · 74.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.9s · import 0.106s · 76MB

74MB installed

● package 74MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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`).

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

diagrams --version

Debug

Known issues

gotchaThe `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.

affects: All versions

gotchaIn 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.

affects: 0.25.1

breakingDiagrams 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.

affects: < 0.25.1 (earlier versions supported Python 3.7+)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'diagrams'

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

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

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`.

Upgrade

Version history

0.25.1latest on PyPI · released Nov 22, 2025

Audit

Dependencies

GraphvizrequiredGraphviz is a required system-level dependency for rendering diagrams. It must be installed separately from the Python package.

Agent activity

55 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mingrammer/diagrams ↗

packagehttps://pypi.org/project/diagrams/ ↗

homepagehttps://diagrams.mingrammer.com ↗