# podman-container-tools/buildah architecture

> Architecture diagram of the GitHub repository podman-container-tools/buildah, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/podman-container-tools/buildah
- Repository: https://github.com/podman-container-tools/buildah

## Overview

Buildah is a daemonless tool and Go API for constructing OCI or Docker-format container images. A typical user workflow starts from a base image or scratch, applies Containerfile/Dockerfile instructions or direct container operations, configures the result, then commits it as an image. The README also documents image transfer and local container/image management. The sampled sources show command initialization, build execution, filesystem copying, and Linux isolation; other command relationships below rely on README descriptions, not inspection of their implementations.

Main entry points: [`cmd/buildah/from.go`](https://github.com/podman-container-tools/buildah/blob/main/cmd/buildah/from.go) (Container commands), [`cmd/buildah/main.go`](https://github.com/podman-container-tools/buildah/blob/main/cmd/buildah/main.go) (CLI dispatcher), [`cmd/buildah/pull.go`](https://github.com/podman-container-tools/buildah/blob/main/cmd/buildah/pull.go) (Image commands), [`imagebuildah/stage_executor.go`](https://github.com/podman-container-tools/buildah/blob/main/imagebuildah/stage_executor.go) (Build stage executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command interface"]
  node_command["CLI dispatcher<br/>[main.go]"]
  node_buildcmd["Build command<br/>[build.go]"]
  node_containerops["Container commands<br/>[from.go]"]
  node_imageops["Image commands<br/>[pull.go]"]
end

subgraph group_build["Image construction"]
  node_buildapi["Build API<br/>[build.go]"]
  node_stage["Build stage executor<br/>[stage_executor.go]"]
  node_copier["Filesystem copier<br/>[copier.go]"]
end

subgraph group_runtime["Container runtime"]
  node_rootfs["Container filesystem<br/>[volumes.go]"]
  node_isolation["Linux isolation<br/>[run_linux.go]"]
  node_mounts["Bind mounts<br/>[mount.go]"]
end

subgraph group_images["Image lifecycle"]
  node_commit["Commit image<br/>[commit.go]"]
  node_transfer["Image transfer<br/>[push.go]"]
  node_imageapi["Image operations API<br/>[image.go]"]
  node_storage[("Local image storage")]
end

node_user(("Buildah user"))
node_registry(("Image registry"))

node_user -->|"invokes"| node_command
node_command -->|"initializes"| node_buildcmd
node_command -->|"initializes"| node_containerops
node_command -.->|"initializes"| node_imageops
node_buildcmd -.->|"executes build"| node_stage
node_stage -->|"copies files"| node_copier
node_stage -->|"uses options"| node_buildapi
node_user -->|"creates container"| node_containerops
node_containerops -.->|"manipulates filesystem"| node_rootfs
node_containerops -.->|"runs command"| node_isolation
node_containerops -.->|"mounts filesystem"| node_mounts
node_user -->|"commits container"| node_commit
node_user -->|"pulls or pushes"| node_imageops
node_imageops -.->|"transfers image"| node_registry
node_imageops -.->|"reads or writes"| node_storage
node_commit -.->|"stores image"| node_storage
node_user -->|"uses Go API"| node_imageapi

click node_command "https://github.com/podman-container-tools/buildah/blob/main/cmd/buildah/main.go"
click node_buildcmd "https://github.com/podman-container-tools/buildah/blob/main/cmd/buildah/build.go"
click node_containerops "https://github.com/podman-container-tools/buildah/blob/main/cmd/buildah/from.go"
click node_imageops "https://github.com/podman-container-tools/buildah/blob/main/cmd/buildah/pull.go"
click node_buildapi "https://github.com/podman-container-tools/buildah/blob/main/define/build.go"
click node_stage "https://github.com/podman-container-tools/buildah/blob/main/imagebuildah/stage_executor.go"
click node_copier "https://github.com/podman-container-tools/buildah/blob/main/copier/copier.go"
click node_rootfs "https://github.com/podman-container-tools/buildah/blob/main/internal/volumes/volumes.go"
click node_isolation "https://github.com/podman-container-tools/buildah/blob/main/chroot/run_linux.go"
click node_mounts "https://github.com/podman-container-tools/buildah/blob/main/bind/mount.go"
click node_commit "https://github.com/podman-container-tools/buildah/blob/main/commit.go"
click node_transfer "https://github.com/podman-container-tools/buildah/blob/main/push.go"
click node_imageapi "https://github.com/podman-container-tools/buildah/blob/main/image.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_command,node_buildcmd,node_containerops,node_imageops,node_user toneBlue
class node_buildapi,node_stage,node_copier toneAmber
class node_rootfs,node_isolation,node_mounts toneMint
class node_commit,node_transfer,node_imageapi,node_storage toneRose
class node_registry toneIndigo
```

## Components

### Command interface

- [CLI dispatcher](https://github.com/podman-container-tools/buildah/blob/main/cmd/buildah/main.go): `cmd/buildah/main.go`
- [Build command](https://github.com/podman-container-tools/buildah/blob/main/cmd/buildah/build.go): `cmd/buildah/build.go`
- [Container commands](https://github.com/podman-container-tools/buildah/blob/main/cmd/buildah/from.go): `cmd/buildah/from.go`
- [Image commands](https://github.com/podman-container-tools/buildah/blob/main/cmd/buildah/pull.go): `cmd/buildah/pull.go`

### Image construction

- [Build API](https://github.com/podman-container-tools/buildah/blob/main/define/build.go): `define/build.go`
- [Build stage executor](https://github.com/podman-container-tools/buildah/blob/main/imagebuildah/stage_executor.go): `imagebuildah/stage_executor.go`
- [Filesystem copier](https://github.com/podman-container-tools/buildah/blob/main/copier/copier.go): `copier/copier.go`

### Container runtime

- [Container filesystem](https://github.com/podman-container-tools/buildah/blob/main/internal/volumes/volumes.go): `internal/volumes/volumes.go`
- [Linux isolation](https://github.com/podman-container-tools/buildah/blob/main/chroot/run_linux.go): `chroot/run_linux.go`
- [Bind mounts](https://github.com/podman-container-tools/buildah/blob/main/bind/mount.go): `bind/mount.go`

### Image lifecycle

- [Commit image](https://github.com/podman-container-tools/buildah/blob/main/commit.go): `commit.go`
- [Image transfer](https://github.com/podman-container-tools/buildah/blob/main/push.go): `push.go`
- [Image operations API](https://github.com/podman-container-tools/buildah/blob/main/image.go): `image.go`
- **Local image storage**

### Other components

- **Buildah user**
- **Image registry**

## Connections

- Buildah user → CLI dispatcher: invokes
- CLI dispatcher → Build command: initializes (evidence: `cmd/buildah/main.go`)
- CLI dispatcher → Container commands: initializes (evidence: `cmd/buildah/main.go`)
- CLI dispatcher → Image commands: initializes
- Build command → Build stage executor: executes build
- Build stage executor → Filesystem copier: copies files (evidence: `imagebuildah/stage_executor.go`)
- Build stage executor → Build API: uses options (evidence: `imagebuildah/stage_executor.go`)
- Buildah user → Container commands: creates container
- Container commands → Container filesystem: manipulates filesystem
- Container commands → Linux isolation: runs command
- Container commands → Bind mounts: mounts filesystem
- Buildah user → Commit image: commits container
- Buildah user → Image commands: pulls or pushes
- Image commands → Image registry: transfers image
- Image commands → Local image storage: reads or writes
- Commit image → Local image storage: stores image
- Buildah user → Image operations API: uses Go API
