0
# DearPyGui
1

2
DearPyGui is a modern, fast and powerful GUI framework for Python that provides an easy-to-use, dynamic, GPU-accelerated, cross-platform graphical user interface toolkit. Built with a C++ core for high performance, it offers complete theme and style control, great performance through GPU-based rendering, stable operation with asynchronous function support, fast graph rendering capable of displaying over 1 million datapoints at 60 fps with zoom and pan capabilities, an intuitive node editor, built-in demo functionality, and comprehensive developer tools including theme inspection, runtime metrics, and debugging capabilities.
3

4
## Package Information
5

6
- **Package Name**: dearpygui
7
- **Package Type**: pypi
8
- **Language**: Python (with C++ extensions)
9
- **Installation**: `pip install dearpygui`
10
- **Platform Support**: Windows, macOS, Linux
11
- **Graphics Backends**: DirectX 11/12, Metal, OpenGL, Vulkan
12

13
## Core Imports
14

15
```python
16
import dearpygui.dearpygui as dpg
17
```
18

19
Additional modules:
20

21
```python
22
import dearpygui.demo as demo  # Built-in demo
23
import dearpygui.experimental as exp  # Experimental features
24
```
25

26
## Basic Usage
27

28
```python
29
import dearpygui.dearpygui as dpg
30

31
# Create application context
32
dpg.create_context()
33

34
# Create a simple window with widgets
35
with dpg.window(label="Hello World", width=400, height=300):
36
    dpg.add_text("Hello, DearPyGui!")
37
    dpg.add_button(label="Click Me!", callback=lambda: print("Button clicked!"))
38
    dpg.add_input_text(label="Text Input", default_value="Type here...")
39
    dpg.add_slider_float(label="Slider", default_value=0.5, min_value=0.0, max_value=1.0)
40

41
# Create and show viewport
42
dpg.create_viewport(title="My Application", width=800, height=600)
43
dpg.setup_dearpygui()
44
dpg.show_viewport()
45

46
# Main application loop
47
dpg.start_dearpygui()
48

49
# Cleanup
50
dpg.destroy_context()
51
```
52

53
## Architecture
54

55
DearPyGui uses an immediate mode GUI paradigm with a hierarchical item system:
56

57
- **Context**: Global application state and resource management
58
- **Viewport**: Main application window (platform window)
59
- **Items**: All GUI elements (windows, widgets, containers) organized in a tree structure
60
- **Registries**: Resource containers for fonts, textures, themes, handlers, and values
61
- **Render Loop**: Continuous rendering cycle with automatic updates
62

63
The framework provides both imperative API calls and context manager patterns for clean, readable code organization.
64

65
## Capabilities
66

67
### Application Lifecycle
68

69
Core application management including context creation, viewport handling, and main loop control. Essential for every DearPyGui application.
70

71
```python { .api }
72
def create_context() -> None: ...
73
def destroy_context() -> None: ...
74
def create_viewport(*, title: str = '', width: int = '', height: int = '') -> None: ...
75
def setup_dearpygui() -> None: ...
76
def show_viewport() -> None: ...
77
def start_dearpygui() -> None: ...
78
def stop_dearpygui() -> None: ...
79
def is_dearpygui_running() -> bool: ...
80
```
81

82
[Application Lifecycle](./application-lifecycle.md)
83

84
### Basic UI Widgets
85

86
Core interactive elements including input controls, buttons, text display, selection widgets, and color pickers. These form the foundation of most GUI applications.
87

88
```python { .api }
89
def add_button(*, label: str = '', callback: Callable = '', **kwargs) -> Union[int, str]: ...
90
def add_text(default_value: str = '', **kwargs) -> Union[int, str]: ...
91
def add_input_text(*, label: str = '', default_value: str = '', **kwargs) -> Union[int, str]: ...
92
def add_slider_float(*, label: str = '', default_value: float = '', min_value: float = '', max_value: float = '', **kwargs) -> Union[int, str]: ...
93
def add_checkbox(*, label: str = '', default_value: bool = '', **kwargs) -> Union[int, str]: ...
94
def add_combo(items: Union[List[str], Tuple[str, ...]], *, label: str = '', **kwargs) -> Union[int, str]: ...
95
def add_color_picker(default_value: Union[List[int], Tuple[int, ...]] = '', **kwargs) -> Union[int, str]: ...
96
```
97

98
[Basic UI Widgets](./widgets.md)
99

100
### Layout & Containers
101

102
Organizational elements for structuring user interfaces including windows, groups, collapsing sections, tabs, menus, and child containers.
103

104
```python { .api }
105
def add_window(*, label: str = '', width: int = '', height: int = '', **kwargs) -> Union[int, str]: ...
106
def add_child_window(*, label: str = '', width: int = '', height: int = '', **kwargs) -> Union[int, str]: ...
107
def add_group(*, horizontal: bool = '', **kwargs) -> Union[int, str]: ...
108
def add_collapsing_header(*, label: str = '', **kwargs) -> Union[int, str]: ...
109
def add_tab_bar(**kwargs) -> Union[int, str]: ...
110
def add_tab(*, label: str = '', **kwargs) -> Union[int, str]: ...
111
def add_menu_bar(**kwargs) -> Union[int, str]: ...
112
def add_menu(*, label: str = '', **kwargs) -> Union[int, str]: ...
113
```
114

115
[Layout & Containers](./layout.md)
116

117
### Plotting & Data Visualization
118

119
Comprehensive plotting system with multiple series types, axes management, and interactive features. Capable of high-performance rendering of large datasets.
120

121
```python { .api }
122
def add_plot(*, label: str = '', width: int = '', height: int = '', **kwargs) -> Union[int, str]: ...
123
def add_plot_axis(axis: int, *, label: str = '', **kwargs) -> Union[int, str]: ...
124
def add_line_series(x: Union[List[float], Tuple[float, ...]], y: Union[List[float], Tuple[float, ...]], **kwargs) -> Union[int, str]: ...
125
def add_scatter_series(x: Union[List[float], Tuple[float, ...]], y: Union[List[float], Tuple[float, ...]], **kwargs) -> Union[int, str]: ...
126
def add_bar_series(x: Union[List[float], Tuple[float, ...]], y: Union[List[float], Tuple[float, ...]], **kwargs) -> Union[int, str]: ...
127
def add_histogram_series(x: Union[List[float], Tuple[float, ...]], **kwargs) -> Union[int, str]: ...
128
```
129

130
[Plotting & Data Visualization](./plotting.md)
131

132
### Drawing & Graphics
133

134
Low-level drawing capabilities for custom graphics including shapes, lines, text rendering, and image display with transformation support.
135

136
```python { .api }
137
def add_drawlist(*, width: int = '', height: int = '', **kwargs) -> Union[int, str]: ...
138
def draw_line(p1: Union[List[float], Tuple[float, ...]], p2: Union[List[float], Tuple[float, ...]], *, color: Union[List[int], Tuple[int, ...]] = '', thickness: float = '') -> None: ...
139
def draw_rectangle(pmin: Union[List[float], Tuple[float, ...]], pmax: Union[List[float], Tuple[float, ...]], *, color: Union[List[int], Tuple[int, ...]] = '', **kwargs) -> None: ...
140
def draw_circle(center: Union[List[float], Tuple[float, ...]], radius: float, *, color: Union[List[int], Tuple[int, ...]] = '', **kwargs) -> None: ...
141
def draw_text(pos: Union[List[float], Tuple[float, ...]], text: str, *, color: Union[List[int], Tuple[int, ...]] = '', size: float = '') -> None: ...
142
```
143

144
[Drawing & Graphics](./drawing.md)
145

146
### Event Handling
147

148
Comprehensive event system for user interactions including mouse events, keyboard input, and item-specific callbacks.
149

150
```python { .api }
151
def add_handler_registry(**kwargs) -> Union[int, str]: ...
152
def add_mouse_click_handler(*, callback: Callable = '', **kwargs) -> Union[int, str]: ...
153
def add_key_press_handler(*, callback: Callable = '', **kwargs) -> Union[int, str]: ...
154
def add_item_clicked_handler(*, callback: Callable = '', **kwargs) -> Union[int, str]: ...
155
def set_frame_callback(frame: int, callback: Callable) -> None: ...
156
```
157

158
[Event Handling](./events.md)
159

160
### Tables & Data Display
161

162
Structured data presentation with sortable columns, row highlighting, and cell-level customization for displaying tabular information.
163

164
```python { .api }
165
def add_table(*, label: str = '', **kwargs) -> Union[int, str]: ...
166
def add_table_column(*, label: str = '', **kwargs) -> Union[int, str]: ...
167
def add_table_row(**kwargs) -> Union[int, str]: ...
168
def add_table_cell(**kwargs) -> Union[int, str]: ...
169
def highlight_table_cell(table: Union[int, str], row: int, column: int, color: Union[List[int], Tuple[int, ...]] = '') -> None: ...
170
```
171

172
[Tables & Data Display](./tables.md)
173

174
### Advanced Features
175

176
Specialized functionality including node editors, theming, resource management, file dialogs, and developer tools.
177

178
```python { .api }
179
def add_node_editor(**kwargs) -> Union[int, str]: ...
180
def add_theme(**kwargs) -> Union[int, str]: ...
181
def add_font_registry(**kwargs) -> Union[int, str]: ...
182
def add_texture_registry(**kwargs) -> Union[int, str]: ...
183
def add_file_dialog(*, callback: Callable = '', **kwargs) -> Union[int, str]: ...
184
def show_item_debug() -> None: ...
185
def show_demo() -> None: ...
186
```
187

188
[Advanced Features](./advanced.md)
189

190
## Common Parameters
191

192
Most DearPyGui functions accept these common parameters:
193

194
- **label** (`str`): Display text for the item
195
- **tag** (`Union[int, str]`): Unique identifier for referencing the item
196
- **parent** (`Union[int, str]`): Parent container (defaults to current container stack)
197
- **before** (`Union[int, str]`): Item to insert before
198
- **show** (`bool`): Visibility state (default: True)
199
- **enabled** (`bool`): Interaction state (default: True)
200
- **user_data** (`Any`): Custom data storage
201
- **callback** (`Callable`): Function to call on interaction
202
- **width** (`int`), **height** (`int`): Dimensions
203
- **pos** (`Union[List[int], Tuple[int, ...]]`): Position [x, y]
204

205
## Item Management
206

207
```python { .api }
208
def configure_item(item: Union[int, str], **kwargs) -> None: ...
209
def get_item_configuration(item: Union[int, str]) -> dict: ...
210
def get_value(item: Union[int, str]) -> Any: ...
211
def set_value(item: Union[int, str], value: Any) -> None: ...
212
def delete_item(item: Union[int, str]) -> None: ...
213
def does_item_exist(item: Union[int, str]) -> bool: ...
214
```
215

216
## Context Managers
217

218
DearPyGui provides context managers for container widgets:
219

220
```python
221
with dpg.window(label="My Window"):
222
    # Widgets automatically added to window
223
    dpg.add_text("Hello!")
224
    
225
    with dpg.group(horizontal=True):
226
        dpg.add_button(label="Button 1")
227
        dpg.add_button(label="Button 2")
228
```
229

230
## Error Handling
231

232
DearPyGui functions may raise exceptions for:
233
- Invalid item IDs or tags
234
- Mismatched parent-child relationships  
235
- Invalid parameter values
236
- Resource allocation failures
237

238
Use `does_item_exist()` to check item validity before operations.
239

240
## Performance Considerations
241

242
- Use `add_clipper()` for large lists to improve rendering performance
243
- Bind data to value registries for efficient updates
244
- Use GPU-accelerated plotting for large datasets
245
- Consider `show=False` for initially hidden items to reduce initial load
246
- Use context managers for cleaner resource management