# python-poetry/poetry architecture

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

- Interactive diagram: https://gitdiagram.com/python-poetry/poetry
- Repository: https://github.com/python-poetry/poetry

## Overview

Poetry is a command-line frontend for declaring, resolving, locking, building, installing, and publishing Python projects. The main workflow starts with a user command, loads project metadata and configuration, resolves dependencies against repositories, records a lockfile, then installs packages into a managed Python environment. Separate branches cover package building and publishing, project scaffolding, and plugins. The graph uses README statements and SOURCE INDEX references; some runtime connections are dashed because the relevant command implementations were not sampled.

Main entry points: [`src/poetry/console/commands`](https://github.com/python-poetry/poetry/tree/main/src/poetry/console/commands) (Project commands), [`src/poetry/repositories/http_repository.py`](https://github.com/python-poetry/poetry/blob/main/src/poetry/repositories/http_repository.py) (HTTP repositories), [`src/poetry/console/application.py`](https://github.com/python-poetry/poetry/blob/main/src/poetry/console/application.py) (CLI application), [`src/poetry/factory.py`](https://github.com/python-poetry/poetry/blob/main/src/poetry/factory.py) (Project factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and project setup"]
  node_app["CLI application<br/>[application.py]"]
  node_factory["Project factory<br/>[factory.py]"]
  node_project["Project model<br/>[poetry.py]"]
  node_commands["Project commands"]
end

subgraph group_resolution["Dependency resolution"]
  node_solver["Version solver<br/>[version_solver.py]"]
  node_provider["Package provider<br/>[provider.py]"]
  node_pool["Repository pool<br/>[repository_pool.py]"]
  node_httprepo["HTTP repositories<br/>[http_repository.py]"]
  node_pypi["PyPI repository<br/>[pypi_repository.py]"]
  node_linkjson["Simple API links<br/>[json.py]"]
  node_locker["Lockfile manager<br/>[locker.py]"]
  node_lockfile["poetry.lock"]
end

subgraph group_install["Installation and environments"]
  node_installer["Installer executor<br/>[executor.py]"]
  node_envmanager["Environment manager<br/>[env_manager.py]"]
  node_python[("Python environment")]
end

subgraph group_package["Build and publishing"]
  node_build["Package builders"]
  node_publish["Package publisher<br/>[publisher.py]"]
end

subgraph group_platform["Configuration and extensions"]
  node_config["Configuration<br/>[config.py]"]
  node_plugins["Plugin manager<br/>[plugin_manager.py]"]
  node_auth["HTTP authentication<br/>[authenticator.py]"]
  node_isolated["Isolated builds<br/>[isolated_build.py]"]
end

node_user(("Project user"))
node_index{{"Package index"}}
node_registry{{"Package registry"}}

node_user -->|"runs command"| node_app
node_app -->|"loads project"| node_factory
node_factory -->|"creates model"| node_project
node_factory -->|"configures"| node_config
node_factory -->|"creates locker"| node_locker
node_app -->|"loads commands"| node_commands
node_commands -.->|"resolves dependencies"| node_solver
node_solver -->|"queries"| node_provider
node_provider -->|"queries repositories"| node_pool
node_pool -.->|"dispatches lookup"| node_httprepo
node_httprepo -->|"uses authentication"| node_auth
node_httprepo -->|"fetches package data"| node_index
node_pypi -->|"extends access"| node_httprepo
node_httprepo -->|"parses listings"| node_linkjson
node_commands -.->|"records lock"| node_locker
node_locker -->|"reads and writes"| node_lockfile
node_commands -.->|"runs install"| node_installer
node_installer -.->|"targets environment"| node_envmanager
node_envmanager -->|"manages"| node_python
node_commands -.->|"builds distributions"| node_build
node_commands -.->|"publishes packages"| node_publish
node_publish -.->|"uploads package"| node_registry
node_app -->|"loads plugins"| node_plugins
node_installer -->|"uses build isolation"| node_isolated

click node_app "https://github.com/python-poetry/poetry/blob/main/src/poetry/console/application.py"
click node_factory "https://github.com/python-poetry/poetry/blob/main/src/poetry/factory.py"
click node_project "https://github.com/python-poetry/poetry/blob/main/src/poetry/poetry.py"
click node_commands "https://github.com/python-poetry/poetry/tree/main/src/poetry/console/commands"
click node_solver "https://github.com/python-poetry/poetry/blob/main/src/poetry/mixology/version_solver.py"
click node_provider "https://github.com/python-poetry/poetry/blob/main/src/poetry/puzzle/provider.py"
click node_pool "https://github.com/python-poetry/poetry/blob/main/src/poetry/repositories/repository_pool.py"
click node_httprepo "https://github.com/python-poetry/poetry/blob/main/src/poetry/repositories/http_repository.py"
click node_pypi "https://github.com/python-poetry/poetry/blob/main/src/poetry/repositories/pypi_repository.py"
click node_linkjson "https://github.com/python-poetry/poetry/blob/main/src/poetry/repositories/link_sources/json.py"
click node_locker "https://github.com/python-poetry/poetry/blob/main/src/poetry/packages/locker.py"
click node_installer "https://github.com/python-poetry/poetry/blob/main/src/poetry/installation/executor.py"
click node_envmanager "https://github.com/python-poetry/poetry/blob/main/src/poetry/utils/env/env_manager.py"
click node_build "https://github.com/python-poetry/poetry/tree/main/src/poetry/masonry/builders"
click node_publish "https://github.com/python-poetry/poetry/blob/main/src/poetry/publishing/publisher.py"
click node_config "https://github.com/python-poetry/poetry/blob/main/src/poetry/config/config.py"
click node_plugins "https://github.com/python-poetry/poetry/blob/main/src/poetry/plugins/plugin_manager.py"
click node_auth "https://github.com/python-poetry/poetry/blob/main/src/poetry/utils/authenticator.py"
click node_isolated "https://github.com/python-poetry/poetry/blob/main/src/poetry/utils/isolated_build.py"

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_app,node_factory,node_project,node_commands,node_user toneBlue
class node_solver,node_provider,node_pool,node_httprepo,node_pypi,node_linkjson,node_locker,node_lockfile toneAmber
class node_installer,node_envmanager,node_python toneMint
class node_build,node_publish toneRose
class node_config,node_plugins,node_auth,node_isolated,node_index,node_registry toneIndigo
```

## Components

### CLI and project setup

- [CLI application](https://github.com/python-poetry/poetry/blob/main/src/poetry/console/application.py): `src/poetry/console/application.py`
- [Project factory](https://github.com/python-poetry/poetry/blob/main/src/poetry/factory.py): `src/poetry/factory.py`
- [Project model](https://github.com/python-poetry/poetry/blob/main/src/poetry/poetry.py): `src/poetry/poetry.py`
- [Project commands](https://github.com/python-poetry/poetry/tree/main/src/poetry/console/commands): `src/poetry/console/commands`

### Dependency resolution

- [Version solver](https://github.com/python-poetry/poetry/blob/main/src/poetry/mixology/version_solver.py): `src/poetry/mixology/version_solver.py`
- [Package provider](https://github.com/python-poetry/poetry/blob/main/src/poetry/puzzle/provider.py): `src/poetry/puzzle/provider.py`
- [Repository pool](https://github.com/python-poetry/poetry/blob/main/src/poetry/repositories/repository_pool.py): `src/poetry/repositories/repository_pool.py`
- [HTTP repositories](https://github.com/python-poetry/poetry/blob/main/src/poetry/repositories/http_repository.py): `src/poetry/repositories/http_repository.py`
- [PyPI repository](https://github.com/python-poetry/poetry/blob/main/src/poetry/repositories/pypi_repository.py): `src/poetry/repositories/pypi_repository.py`
- [Simple API links](https://github.com/python-poetry/poetry/blob/main/src/poetry/repositories/link_sources/json.py): `src/poetry/repositories/link_sources/json.py`
- [Lockfile manager](https://github.com/python-poetry/poetry/blob/main/src/poetry/packages/locker.py): `src/poetry/packages/locker.py`
- **poetry.lock**

### Installation and environments

- [Installer executor](https://github.com/python-poetry/poetry/blob/main/src/poetry/installation/executor.py): `src/poetry/installation/executor.py`
- [Environment manager](https://github.com/python-poetry/poetry/blob/main/src/poetry/utils/env/env_manager.py): `src/poetry/utils/env/env_manager.py`
- **Python environment**

### Build and publishing

- [Package builders](https://github.com/python-poetry/poetry/tree/main/src/poetry/masonry/builders): `src/poetry/masonry/builders`
- [Package publisher](https://github.com/python-poetry/poetry/blob/main/src/poetry/publishing/publisher.py): `src/poetry/publishing/publisher.py`

### Configuration and extensions

- [Configuration](https://github.com/python-poetry/poetry/blob/main/src/poetry/config/config.py): `src/poetry/config/config.py`
- [Plugin manager](https://github.com/python-poetry/poetry/blob/main/src/poetry/plugins/plugin_manager.py): `src/poetry/plugins/plugin_manager.py`
- [HTTP authentication](https://github.com/python-poetry/poetry/blob/main/src/poetry/utils/authenticator.py): `src/poetry/utils/authenticator.py`
- [Isolated builds](https://github.com/python-poetry/poetry/blob/main/src/poetry/utils/isolated_build.py): `src/poetry/utils/isolated_build.py`

### Other components

- **Project user**
- **Package index**
- **Package registry**

## Connections

- Project user → CLI application: runs command (evidence: `README.md`)
- CLI application → Project factory: loads project (evidence: `src/poetry/console/application.py`)
- Project factory → Project model: creates model (evidence: `src/poetry/factory.py`)
- Project factory → Configuration: configures (evidence: `src/poetry/factory.py`)
- Project factory → Lockfile manager: creates locker (evidence: `src/poetry/factory.py`)
- CLI application → Project commands: loads commands (evidence: `src/poetry/console/application.py`)
- Project commands → Version solver: resolves dependencies
- Version solver → Package provider: queries (evidence: `src/poetry/mixology/version_solver.py`)
- Package provider → Repository pool: queries repositories (evidence: `src/poetry/puzzle/provider.py`)
- Repository pool → HTTP repositories: dispatches lookup
- HTTP repositories → HTTP authentication: uses authentication (evidence: `src/poetry/repositories/http_repository.py`)
- HTTP repositories → Package index: fetches package data (evidence: `src/poetry/repositories/http_repository.py`)
- PyPI repository → HTTP repositories: extends access (evidence: `src/poetry/repositories/pypi_repository.py`)
- HTTP repositories → Simple API links: parses listings (evidence: `src/poetry/repositories/http_repository.py`)
- Project commands → Lockfile manager: records lock
- Lockfile manager → poetry.lock: reads and writes (evidence: `src/poetry/packages/locker.py`)
- Project commands → Installer executor: runs install
- Installer executor → Environment manager: targets environment
- Environment manager → Python environment: manages (evidence: `src/poetry/utils/env/env_manager.py`)
- Project commands → Package builders: builds distributions
- Project commands → Package publisher: publishes packages
- Package publisher → Package registry: uploads package
- CLI application → Plugin manager: loads plugins (evidence: `src/poetry/console/application.py`)
- Installer executor → Isolated builds: uses build isolation (evidence: `src/poetry/installation/executor.py`)
