# conan-io/conan architecture

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

- Interactive diagram: https://gitdiagram.com/conan-io/conan
- Repository: https://github.com/conan-io/conan

## Overview

1. **What this repository is**
   Conan is a Python-based C/C++ package manager. The codebase is organized around a user-facing CLI, a programmatic Conan API, an internal dependency-resolution/core engine, a large set of recipe helpers (“tools”), and an optional embedded Conan Server implementation.

2. **Primary entry points**
   The two main entry surfaces are:
   - `conan/cli/*`: command-line parsing and command dispatch for `conan install`, `create`, `upload`, `search`, `profile`, `remote`, etc.
   - `conan/api/conan_api.py` plus `conan/api/subapi/*`: the programmatic API used by the CLI and tests.
   Both ultimately delegate into the internal engine rather than implementing package logic themselves.

3. **CLI layer**
   `conan/cli/cli.py`, `args.py`, and `commands/*` map shell commands to high-level operations. `exit_codes.py` and printers/formatters handle output and result formatting. The CLI is mostly an orchestration layer: parse arguments, call API methods, format results, and exit with the correct code.

4. **API and sub-APIs**
   `conan/api/subapi/*` groups functionality by domain: install, export, create/new, upload, remotes, profiles, graph, cache, list, lockfiles, workspace, etc. This layer is the main contract above the engine and is where command semantics are centralized. `conan/api/model/*` contains typed result models for lists, references, remotes, and outputs.

5. **Core package-management engine**
   The real package resolution and lifecycle logic lives under `conan/internal/*`. Key subsystems include:
   - `internal/graph/*` for dependency graph construction, binary/package ID computation, compatibility, version-range resolution, and install graphs.
   - `internal/cache/*` for the local Conan cache, database tables, integrity checks, and layout.
   - `internal/loader.py`, `source.py`, `methods.py`, and `model/*` for loading recipes, representing Conanfiles, settings/options, manifests, lockfiles, layouts, and metadata.
   This is the boundary where package identity, dependency order, and cache state are decided.

6. **Local-vs-remote data flow**
   Package operations flow between:
   - local recipes/cache (`internal/cache`, `internal/model`, `internal/local`)
   - remote registries via REST (`internal/rest`, `api/subapi/remotes`, `api/subapi/download`, `api/subapi/upload`)
   - graph resolution (`internal/graph`)
   For install/create/upload workflows, the engine resolves a graph, checks cache for binaries, downloads missing artifacts from remotes, and uploads built packages back to remotes when requested.

7. **Remote and transport subsystem**
   `conan/internal/rest/*` implements HTTP client behavior for Conan remotes, authentication, downloads/uploads, and local recipe index support. The remote manager and credential handling are separate from graph logic, so network concerns are isolated from package modeling. This subsystem is what connects Conan clients to Artifactory or other Conan-compatible repositories.

8. **Recipe authoring and build-system integration**
   `conan/tools/*` is a large recipe-helper library exposed to Conan recipes. It provides toolchains, dependency generators, environment managers, and utility helpers for major ecosystems:
   - CMake, Meson, Autotools/GNU Make, MSBuild/NMake, Bazel, Premake, Qbs, SCons
   - Apple, Android, Intel, ROS, SBOM, SCM/Git, system package managers
   These modules are not the package manager core; they are adapters that generate build files, env scripts, or metadata for consumer projects.

9. **Python recipe/runtime model**
   Recipes and model objects are Python-centric. `conan/internal/model/*` and `conan/internal/methods.py` define the recipe interface, settings/options, package info, version handling, lockfiles, and workspace behavior. `conan/cps/*` adds CPS-related support. Conan’s architecture relies on executing recipe code in a controlled loader/runtime rather than parsing declarative metadata alone.

10. **Execution environments and runners**
   `conan/internal/runner/*` abstracts how Conan invokes commands in Docker, SSH, and WSL contexts, while `internal/util/runners.py` and related helpers support command execution. This matters for cross-platform builds and test/package execution because the toolchain setup can happen in isolated or remote environments.

11. **Legacy/embedded server**
   The `conans/server/*` tree is a separate, older Conan Server implementation. It includes REST controllers, auth plugins, storage adapters, JWT/basic-auth handling, and server launch/migration logic. Its boundaries are distinct from the client package manager: it stores packages/revisions and serves them over HTTP, but it is not the same code path as the Conan client’s local cache engine.

12. **Compatibility and transition boundaries**
   The repo contains both `conan/*` and `conans/*`, reflecting modern Conan 2 client code plus compatibility/legacy server/client modules. That split is important for architecture diagrams: the client package manager and the embedded server are related but not the same subsystem, and many tests cover cross-version behavior, migrations, and legacy flows.

13. **Testing and CI as architecture support**
   The `test/`, `conan/test/`, and `.github/workflows/*` trees show heavy test investment around all major boundaries: CLI, graph resolution, cache behavior, remote auth/download/upload, toolchains, and server features. CI runs matrixed platform tests and coverage; Docker is used for some conan tests and integration scenarios. This indicates the repo’s architecture is highly portability- and regression-driven.

Main entry points: [`conan/internal`](https://github.com/conan-io/conan/tree/develop2/conan/internal) (Core engine), [`test`](https://github.com/conan-io/conan/tree/develop2/test) (Tests), [`conan/cli/cli.py`](https://github.com/conan-io/conan/blob/develop2/conan/cli/cli.py) (CLI), [`conans/server`](https://github.com/conan-io/conan/tree/develop2/conans/server) (Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Conan client"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_cli_commands["Commands<br/>command mapping"]
  node_api["Conan API<br/>public api<br/>[conan_api.py]"]
  node_subapis["Sub-APIs<br/>domain api"]
  node_api_models["API models<br/>dto models"]
  node_engine["Core engine<br/>package manager core"]
  node_graph["Dependency graph<br/>resolution engine"]
  node_cache[("Local cache<br/>cache engine")]
  node_models["Recipe model<br/>recipe runtime"]
  node_loader["Loader<br/>recipe loading<br/>[loader.py]"]
  node_rest["Remote REST<br/>transport"]
  node_runner["Runners<br/>execution env"]
  node_tools["Conan tools<br/>recipe helpers"]
  node_cps["CPS support<br/>interop"]
end

subgraph group_legacy["Legacy server"]
  node_legacy_server["Server"]
  node_server_rest["Server REST<br/>server api"]
  node_server_auth["Server auth"]
  node_server_store["Server store<br/>storage"]
end

subgraph group_tests["Tests"]
  node_tests["Tests<br/>verification"]
end

node_cli -->|"dispatches"| node_cli_commands
node_cli -->|"calls"| node_api
node_cli -->|"orchestrates"| node_subapis
node_api -->|"exposes"| node_subapis
node_subapis -->|"delegates to"| node_engine
node_subapis -->|"returns"| node_api_models
node_engine -->|"loads"| node_loader
node_engine -->|"uses"| node_models
node_engine -->|"resolves"| node_graph
node_engine -->|"reads/writes"| node_cache
node_engine -->|"syncs"| node_rest
node_engine -->|"executes"| node_runner
node_engine -->|"provides"| node_tools
node_engine -->|"supports"| node_cps
node_rest -->|"downloads to"| node_cache
node_rest -->|"feeds"| node_graph
node_graph -->|"interprets"| node_models
node_cache -->|"stores"| node_models
node_legacy_server -->|"serves"| node_server_rest
node_legacy_server -->|"authorizes"| node_server_auth
node_legacy_server -->|"persists"| node_server_store
node_tests -.->|"covers"| node_cli
node_tests -.->|"covers"| node_engine
node_tests -.->|"covers"| node_rest
node_tests -.->|"covers"| node_tools
node_tests -.->|"covers"| node_legacy_server

click node_cli "https://github.com/conan-io/conan/blob/develop2/conan/cli/cli.py"
click node_cli_commands "https://github.com/conan-io/conan/tree/develop2/conan/cli/commands"
click node_api "https://github.com/conan-io/conan/blob/develop2/conan/api/conan_api.py"
click node_subapis "https://github.com/conan-io/conan/tree/develop2/conan/api/subapi"
click node_api_models "https://github.com/conan-io/conan/tree/develop2/conan/api/model"
click node_engine "https://github.com/conan-io/conan/tree/develop2/conan/internal"
click node_graph "https://github.com/conan-io/conan/tree/develop2/conan/internal/graph"
click node_cache "https://github.com/conan-io/conan/tree/develop2/conan/internal/cache"
click node_models "https://github.com/conan-io/conan/tree/develop2/conan/internal/model"
click node_loader "https://github.com/conan-io/conan/blob/develop2/conan/internal/loader.py"
click node_rest "https://github.com/conan-io/conan/tree/develop2/conan/internal/rest"
click node_runner "https://github.com/conan-io/conan/tree/develop2/conan/internal/runner"
click node_tools "https://github.com/conan-io/conan/tree/develop2/conan/tools"
click node_cps "https://github.com/conan-io/conan/tree/develop2/conan/cps"
click node_legacy_server "https://github.com/conan-io/conan/tree/develop2/conans/server"
click node_server_rest "https://github.com/conan-io/conan/tree/develop2/conans/server/rest"
click node_server_auth "https://github.com/conan-io/conan/tree/develop2/conans/server/crypto"
click node_server_store "https://github.com/conan-io/conan/tree/develop2/conans/server/store"
click node_tests "https://github.com/conan-io/conan/tree/develop2/test"

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_cli,node_cli_commands,node_api,node_subapis,node_api_models,node_engine,node_graph,node_cache,node_models,node_loader,node_rest,node_runner,node_tools,node_cps toneBlue
class node_legacy_server,node_server_rest,node_server_auth,node_server_store toneAmber
class node_tests toneMint
```

## Components

### Conan client

Modern Conan 2 client package manager subsystems.

- [CLI](https://github.com/conan-io/conan/blob/develop2/conan/cli/cli.py): entrypoint · Shell command parsing, dispatch, output, and exit codes. · `conan/cli/cli.py`
- [Commands](https://github.com/conan-io/conan/tree/develop2/conan/cli/commands): command mapping · Command modules that translate subcommands into high-level operations. · `conan/cli/commands`
- [Conan API](https://github.com/conan-io/conan/blob/develop2/conan/api/conan_api.py): public api · Programmatic entrypoint used by the CLI and integrations. · `conan/api/conan_api.py`
- [Sub-APIs](https://github.com/conan-io/conan/tree/develop2/conan/api/subapi): domain api · Domain-oriented API layer for install, create, upload, remotes, graph, cache, profiles, lockfiles, and workspace. · `conan/api/subapi`
- [API models](https://github.com/conan-io/conan/tree/develop2/conan/api/model): dto models · Typed output and list/reference/remote models returned by the API. · `conan/api/model`
- [Core engine](https://github.com/conan-io/conan/tree/develop2/conan/internal): package manager core · Internal recipe loading, model handling, cache state, graph resolution, and execution plumbing. · `conan/internal`
- [Dependency graph](https://github.com/conan-io/conan/tree/develop2/conan/internal/graph): resolution engine · Builds graphs, resolves versions, computes package IDs, compatibility, and install order. · `conan/internal/graph`
- [Local cache](https://github.com/conan-io/conan/tree/develop2/conan/internal/cache): cache engine · Local recipe and package cache, database tables, layout, and integrity checks. · `conan/internal/cache`
- [Recipe model](https://github.com/conan-io/conan/tree/develop2/conan/internal/model): recipe runtime · Conanfile, settings, options, manifests, lockfiles, layouts, and related runtime models. · `conan/internal/model`
- [Loader](https://github.com/conan-io/conan/blob/develop2/conan/internal/loader.py): recipe loading · Loads and prepares recipe code and recipe metadata for the engine. · `conan/internal/loader.py`
- [Remote REST](https://github.com/conan-io/conan/tree/develop2/conan/internal/rest): transport · HTTP client, auth, download/upload, remote manager, and route handling for Conan remotes. · `conan/internal/rest`
- [Runners](https://github.com/conan-io/conan/tree/develop2/conan/internal/runner): execution env · Command execution abstractions for Docker, SSH, and WSL environments. · `conan/internal/runner`
- [Conan tools](https://github.com/conan-io/conan/tree/develop2/conan/tools): recipe helpers · Recipe helper library for toolchains, generators, envs, filesystem helpers, SCM, and platform adapters. · `conan/tools`
- [CPS support](https://github.com/conan-io/conan/tree/develop2/conan/cps): interop · CPS-related support integrated with the Conan recipe/tooling model. · `conan/cps`

### Legacy server

Embedded Conan Server implementation and compatibility tree.

- [Server](https://github.com/conan-io/conan/tree/develop2/conans/server): legacy server · Older embedded Conan Server implementation with REST controllers, auth, storage, and launch/migration logic. · `conans/server`
- [Server REST](https://github.com/conan-io/conan/tree/develop2/conans/server/rest): server api · Bottle-based REST controllers, routes, and API v2 services for server operations. · `conans/server/rest`
- [Server auth](https://github.com/conan-io/conan/tree/develop2/conans/server/crypto): auth · JWT and basic-auth plugins plus authorization services for the server. · `conans/server/crypto`
- [Server store](https://github.com/conan-io/conan/tree/develop2/conans/server/store): storage · Disk-backed server package storage and revision handling. · `conans/server/store`

### Tests

Functional, integration, and unit coverage around major boundaries.

- [Tests](https://github.com/conan-io/conan/tree/develop2/test): verification · Functional, integration, unit, and performance tests covering client, tools, graph, remote, and server behavior. · `test`

## Connections

- CLI → Commands: dispatches · CLI subcommands are mapped to command handlers.
- CLI → Conan API: calls · Command execution is routed through the Conan API.
- CLI → Sub-APIs: orchestrates · CLI behavior is mostly orchestration over domain sub-APIs.
- Conan API → Sub-APIs: exposes · The public API is organized into domain sub-APIs.
- Sub-APIs → Core engine: delegates to · Sub-APIs centralize semantics and delegate core work to internal engine subsystems.
- Sub-APIs → API models: returns · API calls surface typed result models.
- Core engine → Loader: loads · The engine loads recipes and prepared Conanfile state.
- Core engine → Recipe model: uses · Core behavior is built around internal recipe/runtime models.
- Core engine → Dependency graph: resolves · Dependency resolution and package identity are decided by the graph subsystem.
- Core engine → Local cache: reads/writes · The engine consults and updates the local cache.
- Core engine → Remote REST: syncs · Remote package and recipe flows use REST transport.
- Core engine → Runners: executes · Build and test actions can run in isolated execution environments.
- Core engine → Conan tools: provides · Recipe helpers and generators are part of the client surface built on the engine.
- Core engine → CPS support: supports · CPS support plugs into the client runtime model.
- Remote REST → Local cache: downloads to · Remote artifacts are cached locally after retrieval.
- Remote REST → Dependency graph: feeds · Resolution may trigger remote metadata/package discovery.
- Dependency graph → Recipe model: interprets · Graph computation depends on recipe, settings, version, and lockfile models.
- Local cache → Recipe model: stores · Cache state persists recipes, packages, manifests, and metadata.
- Server → Server REST: serves · The server exposes REST endpoints for clients.
- Server → Server auth: authorizes · Authentication and authorization are handled by server-side crypto/auth components.
- Server → Server store: persists · Packages and revisions are stored on disk.
- Tests → CLI: covers · Functional and integration tests exercise CLI flows.
- Tests → Core engine: covers · Graph, cache, loader, and model behavior are heavily tested.
- Tests → Remote REST: covers · Remote auth, download, upload, and requester behavior are tested.
- Tests → Conan tools: covers · Toolchain and helper modules are validated with extensive tests.
- Tests → Server: covers · Server auth, REST, storage, and migration flows are covered.
