Skip to content
Get packs

Guide · Open source

How to use diagrams: draw cloud architecture as Python code

Updated · written with AI from the project's own documentation and checked against our catalogue data

Diagrams is an open-source Python library for drawing cloud system architecture diagrams in code instead of a drawing tool. This guide is for engineers comfortable with basic Python who want to sketch or document an architecture. By the end you will know what to install, how the library is meant to be used, and where it fits compared with other diagram tools.

Diagramsmingrammer/diagrams · ★ 42.8k · MIT

Quick start

  1. 1Check prerequisites. Confirm you have Python 3.9 or higher and install Graphviz. On macOS you can use Homebrew.
  2. 2Install diagrams. Run pip install diagrams, or use pipenv or poetry if your project uses them.
  3. 3Write a diagram in Python. Describe your nodes and the connections between them in a Python file, using the provider icons from the documentation.
  4. 4Render the image. Run the Python file to produce the diagram image.
  5. 5Commit the source. Store the Python file in git so that changes to the architecture show up as code diffs.

What is Diagrams and what does it do?

Diagrams lets you describe a system architecture in Python code and renders the result as a diagram image. It was built for prototyping a new architecture without design tools, and it can also be used to visualise an existing one.

It includes icons for major providers such as AWS, Azure, GCP, Kubernetes, Alibaba Cloud and Oracle Cloud, plus On-Premises nodes, SaaS and major programming frameworks and languages.

Install Python and Graphviz before you start

Diagrams requires Python 3.9 or higher. It renders diagrams using Graphviz, so Graphviz must be installed as well, and the diagrams package is installed after Graphviz is in place.

On macOS, the README suggests installing Graphviz with Homebrew.

  • Check your Python version is 3.9 or higher
  • Install Graphviz from the Graphviz download page, or on macOS with Homebrew
brew install graphviz

Install the diagrams package

The README lists pip, pipenv and poetry as install options. Use whichever matches how your project manages dependencies.

# using pip (pip3) pip install diagrams # using pipenv pipenv install diagrams # using poetry poetry add diagrams

Try it without installing anything

If you want to test the library first, the project offers an online playground that runs diagrams in your browser. It supports node search, autocompletion, PNG, SVG and JPEG export, and shareable links.

The playground is a good option if you cannot install Graphviz or Python yet, since it needs neither.

  • Open diagrams.mingrammer.com/playground
  • Write Diagram as Code and see the rendered result
  • Export as PNG, SVG or JPEG

Keep diagrams in version control

Because the diagram is a Python file, you can track changes in any version control system. Reviewers can read the code diff to see what changed in the architecture.

Diagrams does not connect to real cloud resources. It does not control infrastructure and does not generate Terraform or CloudFormation code. It only draws the diagram.

Where to find nodes and examples

The project documentation includes a quick start, guides, a full list of available nodes for each provider, and an examples page with sample diagrams.

Diagrams can be used with other tools such as CloudFormation diagram scripts or Kubernetes diagram generators, which are listed in the project README.

  • Quick start: diagrams.mingrammer.com/docs/getting-started/installation
  • Guides: diagrams.mingrammer.com/docs/guides/diagram
  • Node lists: diagrams.mingrammer.com/docs/nodes/aws
  • Examples: diagrams.mingrammer.com/docs/getting-started/examples

What people use it for

  • Sketching a new cloud architecture quickly before a design review
  • Documenting an existing cloud setup by drawing it from code
  • Keeping architecture diagrams in a git repository for review
  • Creating example architecture diagrams for documentation, as Apache Airflow does

Frequently asked questions

Is diagrams free to use?

Yes. The project is released under the MIT licence, as stated in the README. Check the LICENSE file in the repository for the full terms.

What does diagrams require to run?

It requires Python 3.9 or higher and Graphviz, which the library uses to render the diagram. The README says to install Graphviz before installing the diagrams package.

How do I install diagrams with pip?

Run pip install diagrams. The README also lists pipenv install diagrams and poetry add diagrams as alternatives.

Does diagrams create Terraform or CloudFormation code?

No. The README states it does not control cloud resources and does not generate CloudFormation or Terraform code. It only draws architecture diagrams.

Do I need to know Python to use diagrams?

Yes, diagrams are written in Python code. The project is aimed at users who are comfortable with basic Python. If you want a visual editor, it does not offer one, though the online playground lets you test code in a browser.

How does diagrams compare with PlantUML, Mermaid or Structurizr?

All of these are diagram-as-code tools. Diagrams focuses on cloud provider and on-premises icons written in Python, while PlantUML and Mermaid use their own text syntaxes. Graphviz is the rendering engine that diagrams uses. Pick based on your language preference and the icons you need.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Diagrams suits engineers who want to sketch or document cloud architecture in Python and keep those diagrams in git. It is not a good fit if you need to deploy or manage cloud resources, want a drag-and-drop editor, or cannot install Graphviz and Python 3.9 or higher.

Install options & downloads