# pysimplegui/pysimplegui architecture

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

- Interactive diagram: https://gitdiagram.com/pysimplegui/pysimplegui
- Repository: https://github.com/pysimplegui/pysimplegui

## Overview

PySimpleGUI is a Python wrapper for tkinter that lets application authors define interfaces with compact layouts and interact with them through windows and event loops. The principal workflow is to compose elements into a layout, create a window, read events and values, update elements in response, then close the window. The README and samples also document themes, persistent user settings, graph-based drawing, threaded tasks, and optional drag-and-drop integration. The main implementation is indexed but was not excerpted, so internal implementation details and unshown connections are intentionally omitted.

Main entry points: [`PySimpleGUI/PySimpleGUI.py`](https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py) (Event loop), [`DemoPrograms/Demo_Drag_and_Drop.py`](https://github.com/pysimplegui/pysimplegui/blob/master/DemoPrograms/Demo_Drag_and_Drop.py) (Drag-drop demo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_composition["Interface composition"]
  node_api["PySimpleGUI API<br/>[PySimpleGUI.py]"]
  node_elements["GUI elements<br/>[PySimpleGUI.py]"]
  node_layout["Element layout<br/>[PySimpleGUI.py]"]
end

subgraph group_runtime["Window runtime"]
  node_window["Window<br/>[PySimpleGUI.py]"]
  node_eventloop["Event loop<br/>[PySimpleGUI.py]"]
  node_element_updates["Element updates<br/>[PySimpleGUI.py]"]
end

subgraph group_capabilities["Product capabilities"]
  node_themes["Theme selection<br/>[PySimpleGUI.py]"]
  node_settings[("User settings<br/>[PySimpleGUI.py]")]
  node_graph["Graph drawing<br/>[PySimpleGUI.py]"]
  node_threaded_tasks["Threaded tasks<br/>[PySimpleGUI.py]"]
end

subgraph group_integrations["Optional integrations"]
  node_dnd_demo["Drag-drop demo"]
end

node_developer(("Application author"))
node_tkinter["tkinter"]
node_psgdnd["psgdnd"]

node_developer -->|"uses"| node_api
node_api -->|"wraps"| node_tkinter
node_developer -->|"composes"| node_elements
node_elements -->|"forms"| node_layout
node_developer -->|"creates"| node_window
node_window -->|"reads events"| node_eventloop
node_eventloop -->|"updates"| node_element_updates
node_developer -->|"closes"| node_window
node_developer -->|"selects"| node_themes
node_developer -->|"reads and writes"| node_settings
node_developer -->|"draws and moves"| node_graph
node_eventloop -->|"receives messages"| node_threaded_tasks
node_dnd_demo -->|"registers drops"| node_psgdnd

click node_api "https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py"
click node_elements "https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py"
click node_layout "https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py"
click node_window "https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py"
click node_eventloop "https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py"
click node_element_updates "https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py"
click node_themes "https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py"
click node_settings "https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py"
click node_graph "https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py"
click node_threaded_tasks "https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py"
click node_dnd_demo "https://github.com/pysimplegui/pysimplegui/blob/master/DemoPrograms/Demo_Drag_and_Drop.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_api,node_elements,node_layout toneBlue
class node_window,node_eventloop,node_element_updates toneAmber
class node_themes,node_settings,node_graph,node_threaded_tasks toneMint
class node_dnd_demo toneRose
class node_developer,node_tkinter,node_psgdnd toneIndigo
```

## Components

### Interface composition

- [PySimpleGUI API](https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py): `PySimpleGUI/PySimpleGUI.py`
- [GUI elements](https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py): `PySimpleGUI/PySimpleGUI.py`
- [Element layout](https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py): `PySimpleGUI/PySimpleGUI.py`

### Window runtime

- [Window](https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py): `PySimpleGUI/PySimpleGUI.py`
- [Event loop](https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py): `PySimpleGUI/PySimpleGUI.py`
- [Element updates](https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py): `PySimpleGUI/PySimpleGUI.py`

### Product capabilities

- [Theme selection](https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py): `PySimpleGUI/PySimpleGUI.py`
- [User settings](https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py): `PySimpleGUI/PySimpleGUI.py`
- [Graph drawing](https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py): `PySimpleGUI/PySimpleGUI.py`
- [Threaded tasks](https://github.com/pysimplegui/pysimplegui/blob/master/PySimpleGUI/PySimpleGUI.py): `PySimpleGUI/PySimpleGUI.py`

### Optional integrations

- [Drag-drop demo](https://github.com/pysimplegui/pysimplegui/blob/master/DemoPrograms/Demo_Drag_and_Drop.py): `DemoPrograms/Demo_Drag_and_Drop.py`

### Other components

- **Application author**
- **tkinter**
- **psgdnd**

## Connections

- Application author → PySimpleGUI API: uses (evidence: `README.md`)
- PySimpleGUI API → tkinter: wraps (evidence: `README.md`)
- Application author → GUI elements: composes (evidence: `README.md`)
- GUI elements → Element layout: forms (evidence: `README.md`)
- Application author → Window: creates (evidence: `README.md`)
- Window → Event loop: reads events (evidence: `README.md`)
- Event loop → Element updates: updates (evidence: `README.md`)
- Application author → Window: closes (evidence: `README.md`)
- Application author → Theme selection: selects
- Application author → User settings: reads and writes
- Application author → Graph drawing: draws and moves
- Event loop → Threaded tasks: receives messages (evidence: `DemoPrograms/Demo_Multithreaded_Long_Tasks.py`)
- Drag-drop demo → psgdnd: registers drops (evidence: `DemoPrograms/Demo_Drag_and_Drop.py`)
