# homebrew/brew architecture

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

- Interactive diagram: https://gitdiagram.com/homebrew/brew
- Repository: https://github.com/homebrew/brew

## Overview

Homebrew is a macOS/Linux package manager: users invoke `brew` commands to find, install, update, and manage formulae and casks, with `brew bundle` and `brew services` providing related workflows. The map preserves those distinct product areas, plus package metadata, auditing, and analytics documented by the README. The supplied excerpts chiefly cover services and supporting features; dashed, uncited links mark major runtime relationships that are not directly shown in the sampled source.

Main entry points: [`Library/Homebrew/cmd/install.rb`](https://github.com/homebrew/brew/blob/main/Library/Homebrew/cmd/install.rb) (Install command), [`Library/Homebrew/commands.rb`](https://github.com/homebrew/brew/blob/main/Library/Homebrew/commands.rb) (Brew commands), [`Library/Homebrew/bundle/subcommand/install.rb`](https://github.com/homebrew/brew/blob/main/Library/Homebrew/bundle/subcommand/install.rb) (Bundle command), [`Library/Homebrew/services/cli.rb`](https://github.com/homebrew/brew/blob/main/Library/Homebrew/services/cli.rb) (Service manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command interface"]
  node_commands["Brew commands<br/>[commands.rb]"]
  node_install_cmd["Install command<br/>[install.rb]"]
  node_search_cmd["Search command<br/>[search.rb]"]
  node_update_cmd["Update command<br/>[update.rb]"]
end

subgraph group_packages["Package lifecycle"]
  node_formula["Formula packages<br/>[formula.rb]"]
  node_cask["Cask packages<br/>[cask.rb]"]
  node_download["Source downloads<br/>[downloadable.rb]"]
  node_build["Formula builds<br/>[build.rb]"]
  node_install_actions["Install actions<br/>[formula_actions.rb]"]
  node_installed[("Installed packages")]
end

subgraph group_metadata["Catalog and audit"]
  node_api["Package API<br/>[api.rb]"]
  node_package_index["Packages index<br/>[packages_index.rb]"]
  node_audit["Cask audit<br/>[audit.rb]"]
  node_analytics["Usage analytics<br/>[analytics.rb]"]
end

subgraph group_bundle["Environment bundles"]
  node_bundle_cmd["Bundle command<br/>[install.rb]"]
  node_brewfile["Brewfile DSL<br/>[dsl.rb]"]
  node_bundle_installer["Bundle installer<br/>[installer.rb]"]
end

subgraph group_services["Background services"]
  node_services_cmd["Services command<br/>[services.rb]"]
  node_service_model["Service definition<br/>[service.rb]"]
  node_service_manager["Service manager<br/>[cli.rb]"]
end

node_user(("Homebrew user"))
node_daemon["launchd / systemd"]

node_user -.->|"runs"| node_commands
node_commands -.->|"dispatches"| node_install_cmd
node_commands -.->|"dispatches"| node_search_cmd
node_commands -.->|"dispatches"| node_update_cmd
node_install_cmd -.->|"installs"| node_formula
node_install_cmd -.->|"installs"| node_cask
node_install_cmd -.->|"fetches"| node_download
node_install_cmd -.->|"builds"| node_build
node_install_cmd -.->|"executes"| node_install_actions
node_install_actions -.->|"writes"| node_installed
node_search_cmd -.->|"queries"| node_package_index
node_api -.->|"indexes"| node_package_index
node_audit -.->|"audits"| node_cask
node_user -.->|"runs"| node_bundle_cmd
node_bundle_cmd -.->|"reads"| node_brewfile
node_bundle_cmd -.->|"delegates"| node_bundle_installer
node_user -->|"runs"| node_services_cmd
node_services_cmd -->|"dispatches"| node_service_manager
node_service_manager -.->|"configures"| node_service_model
node_service_manager -.->|"controls"| node_daemon
node_user -.->|"views"| node_analytics

click node_commands "https://github.com/homebrew/brew/blob/main/Library/Homebrew/commands.rb"
click node_install_cmd "https://github.com/homebrew/brew/blob/main/Library/Homebrew/cmd/install.rb"
click node_search_cmd "https://github.com/homebrew/brew/blob/main/Library/Homebrew/cmd/search.rb"
click node_update_cmd "https://github.com/homebrew/brew/blob/main/Library/Homebrew/cmd/update.rb"
click node_formula "https://github.com/homebrew/brew/blob/main/Library/Homebrew/formula.rb"
click node_cask "https://github.com/homebrew/brew/blob/main/Library/Homebrew/cask/cask.rb"
click node_download "https://github.com/homebrew/brew/blob/main/Library/Homebrew/downloadable.rb"
click node_build "https://github.com/homebrew/brew/blob/main/Library/Homebrew/build.rb"
click node_install_actions "https://github.com/homebrew/brew/blob/main/Library/Homebrew/install_steps/formula_actions.rb"
click node_api "https://github.com/homebrew/brew/blob/main/Library/Homebrew/api.rb"
click node_package_index "https://github.com/homebrew/brew/blob/main/Library/Homebrew/api/packages_index.rb"
click node_audit "https://github.com/homebrew/brew/blob/main/Library/Homebrew/cask/audit.rb"
click node_analytics "https://github.com/homebrew/brew/blob/main/Library/Homebrew/api/analytics.rb"
click node_bundle_cmd "https://github.com/homebrew/brew/blob/main/Library/Homebrew/bundle/subcommand/install.rb"
click node_brewfile "https://github.com/homebrew/brew/blob/main/Library/Homebrew/bundle/dsl.rb"
click node_bundle_installer "https://github.com/homebrew/brew/blob/main/Library/Homebrew/bundle/installer.rb"
click node_services_cmd "https://github.com/homebrew/brew/blob/main/Library/Homebrew/cmd/services.rb"
click node_service_model "https://github.com/homebrew/brew/blob/main/Library/Homebrew/service.rb"
click node_service_manager "https://github.com/homebrew/brew/blob/main/Library/Homebrew/services/cli.rb"

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_commands,node_install_cmd,node_search_cmd,node_update_cmd,node_user toneBlue
class node_formula,node_cask,node_download,node_build,node_install_actions,node_installed toneAmber
class node_api,node_package_index,node_audit,node_analytics toneMint
class node_bundle_cmd,node_brewfile,node_bundle_installer toneRose
class node_services_cmd,node_service_model,node_service_manager,node_daemon toneIndigo
```

## Components

### Command interface

- [Brew commands](https://github.com/homebrew/brew/blob/main/Library/Homebrew/commands.rb): `Library/Homebrew/commands.rb`
- [Install command](https://github.com/homebrew/brew/blob/main/Library/Homebrew/cmd/install.rb): `Library/Homebrew/cmd/install.rb`
- [Search command](https://github.com/homebrew/brew/blob/main/Library/Homebrew/cmd/search.rb): `Library/Homebrew/cmd/search.rb`
- [Update command](https://github.com/homebrew/brew/blob/main/Library/Homebrew/cmd/update.rb): `Library/Homebrew/cmd/update.rb`

### Package lifecycle

- [Formula packages](https://github.com/homebrew/brew/blob/main/Library/Homebrew/formula.rb): `Library/Homebrew/formula.rb`
- [Cask packages](https://github.com/homebrew/brew/blob/main/Library/Homebrew/cask/cask.rb): `Library/Homebrew/cask/cask.rb`
- [Source downloads](https://github.com/homebrew/brew/blob/main/Library/Homebrew/downloadable.rb): `Library/Homebrew/downloadable.rb`
- [Formula builds](https://github.com/homebrew/brew/blob/main/Library/Homebrew/build.rb): `Library/Homebrew/build.rb`
- [Install actions](https://github.com/homebrew/brew/blob/main/Library/Homebrew/install_steps/formula_actions.rb): `Library/Homebrew/install_steps/formula_actions.rb`
- **Installed packages**

### Catalog and audit

- [Package API](https://github.com/homebrew/brew/blob/main/Library/Homebrew/api.rb): `Library/Homebrew/api.rb`
- [Packages index](https://github.com/homebrew/brew/blob/main/Library/Homebrew/api/packages_index.rb): `Library/Homebrew/api/packages_index.rb`
- [Cask audit](https://github.com/homebrew/brew/blob/main/Library/Homebrew/cask/audit.rb): `Library/Homebrew/cask/audit.rb`
- [Usage analytics](https://github.com/homebrew/brew/blob/main/Library/Homebrew/api/analytics.rb): `Library/Homebrew/api/analytics.rb`

### Environment bundles

- [Bundle command](https://github.com/homebrew/brew/blob/main/Library/Homebrew/bundle/subcommand/install.rb): `Library/Homebrew/bundle/subcommand/install.rb`
- [Brewfile DSL](https://github.com/homebrew/brew/blob/main/Library/Homebrew/bundle/dsl.rb): `Library/Homebrew/bundle/dsl.rb`
- [Bundle installer](https://github.com/homebrew/brew/blob/main/Library/Homebrew/bundle/installer.rb): `Library/Homebrew/bundle/installer.rb`

### Background services

- [Services command](https://github.com/homebrew/brew/blob/main/Library/Homebrew/cmd/services.rb): `Library/Homebrew/cmd/services.rb`
- [Service definition](https://github.com/homebrew/brew/blob/main/Library/Homebrew/service.rb): `Library/Homebrew/service.rb`
- [Service manager](https://github.com/homebrew/brew/blob/main/Library/Homebrew/services/cli.rb): `Library/Homebrew/services/cli.rb`

### Other components

- **Homebrew user**
- **launchd / systemd**

## Connections

- Homebrew user → Brew commands: runs (evidence: `README.md`)
- Brew commands → Install command: dispatches
- Brew commands → Search command: dispatches
- Brew commands → Update command: dispatches
- Install command → Formula packages: installs
- Install command → Cask packages: installs
- Install command → Source downloads: fetches
- Install command → Formula builds: builds
- Install command → Install actions: executes
- Install actions → Installed packages: writes
- Search command → Packages index: queries
- Package API → Packages index: indexes
- Cask audit → Cask packages: audits
- Homebrew user → Bundle command: runs (evidence: `README.md`)
- Bundle command → Brewfile DSL: reads
- Bundle command → Bundle installer: delegates
- Homebrew user → Services command: runs (evidence: `Library/Homebrew/cmd/services.rb`)
- Services command → Service manager: dispatches (evidence: `Library/Homebrew/cmd/services.rb`)
- Service manager → Service definition: configures
- Service manager → launchd / systemd: controls
- Homebrew user → Usage analytics: views (evidence: `README.md`)
