DFD — Data Flow Diagrams as Code

Describe system architectures as text, get diagrams as SVG, PNG, PDF, and more. Version-controlled, diffable, no GUI needed.

DFD generates Data Flow Diagrams from a simple text-based DSL, rendered via Graphviz. It supports the SA/SD and SA/RT methodologies (Structured Analysis / Structured Design, with real-time extensions) as described by Edward Yourdon.

Complete example

The diagram above is generated from this input:

process   Acquire         Acquire data
process   Compute
control   Control
entity    Device
store     Config          Configuration
channel   API

*         ::>  Control    clock
Control   <::  *          enable
Control   <::  *          disable
Control   ::>? Acquire    sampling

Device    ->>  Acquire    continuous raw data
Acquire   -->  Compute    raw records
Config    <->  Compute    parameters
Compute   -->  API        records

Features

Feature	Description
SA/RT support	Signals, control processes, and channels for real-time and embedded systems
Context diagrams	Generate a top-level SA/SD context diagram (`style context`)
Frames and grouping	Visually group related items
Filters	Render focused subsets of a large master diagram (neighborhood, only/without)
Dependency checking	Verify that all referenced includes and items are consistent
Includes and reuse	Split large diagrams across files, share common item definitions via `include`
Markdown embedding	Embed diagrams directly in Markdown files and generate all images in one pass (`--markdown` mode)
Layout control	Horizontal or vertical orientation, placement constraints between items, relaxed constraints on connections
Styling	Background color, graph title suppression, inline Graphviz attributes, reusable attribute aliases
Multiple output formats	SVG, PNG, PDF, JPG, EPS, and any other format supported by your Graphviz installation (run `dot -Thelp` for the full list), plus raw DOT source

Quick start

uv tool install data-flow-diagram

Create a file hello.dfd:

entity    User
process   App
store     DB

User --> App    request
App  --> DB     query
DB   --> App    result
App  --> User   response

Generate the diagram:

data-flow-diagram hello.dfd -o hello.svg --no-graph-title

You should obtain:

Quick start result

Or pipe directly from stdin:

echo 'entity User
process App
User --> App  request' | data-flow-diagram -o quick.svg --no-graph-title

Stdin pipe result

Installing

For users

Requires Graphviz and uv, which installs the tool user-wide in its own environment, with a suitable Python (3.11+) if none is present. No sudo, no system-wide Python packages.

Linux (Debian/Ubuntu):

sudo apt install graphviz
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install data-flow-diagram

macOS (Homebrew):

brew install graphviz uv
uv tool install data-flow-diagram

pipx users can equivalently run pipx install data-flow-diagram. To upgrade: uv tool upgrade data-flow-diagram.

For developers

Requires GNU Make (pre-installed on most Linux distributions; on macOS, install the Xcode Command Line Tools if not already present: xcode-select --install).

git clone https://github.com/pbauermeister/dfd.git
cd dfd
make all    # installs deps, formats, lints, tests, builds docs

make all auto-detects your OS and installs the required system packages (Debian apt or macOS brew) and uv, which then manages the local .venv and the supported Python versions. Run make help for all available targets. Releases go through GitHub Actions: see engineering/RELEASING.md.

Documentation

Full syntax reference, examples, and advanced features:

Usage

data-flow-diagram -h says:

usage: data-flow-diagram [-h] [--output-file OUTPUT_FILE] [--markdown]
                         [--format FORMAT]
                         [--background-color BACKGROUND_COLOR]
                         [--no-graph-title] [--no-check-dependencies]
                         [--debug] [--version]
                         [INPUT_FILE]

Command-line DFD diagram generator. Converts a textual description into a
graphic file.

positional arguments:
  INPUT_FILE            DFD input file; if omitted, stdin is used

options:
  -h, --help            show this help message and exit
  --output-file OUTPUT_FILE, -o OUTPUT_FILE
                        output file name; pass '-' to use stdout; if omitted,
                        use INPUT_FILE base name with '.svg' extension, or
                        stdout
  --markdown, -m        consider snippets between opening marker: ```data-
                        flow-diagram OUTFILE, and closing marker: ``` allowing
                        to generate all diagrams contained in an INPUT_FILE
                        that is a markdown file
  --format FORMAT, -f FORMAT
                        output format: gif, jpg, tiff, bmp, pnm, eps, pdf, svg
                        (any supported by Graphviz), or dot (raw Graphviz DOT
                        text); default is svg
  --background-color BACKGROUND_COLOR, -b BACKGROUND_COLOR
                        background color name (including 'none' for
                        transparent) in web color notation; see
                        https://developer.mozilla.org/en-
                        US/docs/Web/CSS/color_value for a list of valid names;
                        default is white
  --no-graph-title      suppress graph title
  --no-check-dependencies
                        suppress dependencies checking
  --debug               emit debug messages
  --version, -V         print the version and exit

See https://github.com/pbauermeister/dfd for information, syntax and examples.

Release files for data-flow-diagram 1.18.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for data-flow-diagram 1.18.0
File	Size	Uploaded
data_flow_diagram-1.18.0.tar.gz	52.2 kB	Sep 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for data-flow-diagram 1.18.0
File	Interpreter	ABI	Platform	Reset
data_flow_diagram-1.18.0-py3-none-any.whl 47.7 kB Sep 24, 2026	Python 3	none	any	Details

Total release size: 100.0 kB

Release files / data_flow_diagram-1.18.0.tar.gz

Download URL	data_flow_diagram-1.18.0.tar.gz
Size	52.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`8220fe3555d75cf2fe9c9f061649d10c513bb11006f4a26fe3a95dc220446341`
BLAKE2b-256 checksum How to use checksums	`b9c2e6a230e9b6aa91f8eb5a29620f8aba2c7171322376354b3c278b41d31173`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / data_flow_diagram-1.18.0-py3-none-any.whl

Download URL	data_flow_diagram-1.18.0-py3-none-any.whl
Size	47.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b980ca53fa9e2f9ee450ce99f2a442aa8d66266ea4761919d563646539180050`
BLAKE2b-256 checksum How to use checksums	`c79595e7eaa8ee20211eeda302ba8251b71e20a6245c272239d1999a6fa84fa6`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`