DearPyGui

2.3 · active · verified Fri Apr 17

Dear PyGui is a simple, fast, and powerful Python GUI toolkit that provides a wrapper for the Dear ImGui library. It allows for the rapid creation of highly interactive graphical user interfaces with Python, often used for tools, dashboards, and visualizations. The current version is 2.3, and it maintains an active release cadence with significant updates, including major version bumps for internal dependency upgrades and API changes.

Common errors

```
NameError: name 'dpg' is not defined
```
cause The `dearpygui.dearpygui` module was imported, but the common alias `dpg` was not used or another alias was used inconsistently.

fix Ensure you are consistently importing with `import dearpygui.dearpygui as dpg` and referring to functions with `dpg.function_name()`.
```
RuntimeError: Item with tag '...' already exists.
```
cause You are attempting to add an item with a tag that is already in use. All items in DearPyGui must have unique tags.

fix Either ensure each item has a unique tag (recommended), or check if an item with the desired tag already exists using `dpg.does_item_exist('tag')` before adding it. If you wish to dynamically update an item, use `dpg.set_item_config('tag', **kwargs)` instead of re-adding it.
```
RuntimeError: Dear PyGui context was not created. Please create a context with `dpg.create_context()`
```
cause All DearPyGui operations must occur within an active context, which needs to be explicitly created at the start of your application.

fix Add `dpg.create_context()` at the very beginning of your DearPyGui application logic, before any other `dpg` calls.

Warnings

breaking Version 2.0.0 introduced breaking changes due to internal updates to Dear ImGui and ImPlot. Many function parameters, especially related to styling and item configurations (e.g., `add_text`'s `color` argument directly in the function call), were modified or moved to theme systems.
Fix: Review the official DearPyGui v2.0.0 changelog and updated documentation. Most style parameters are now handled via `dpg.bind_item_theme()` or through global theme settings rather than direct function arguments.
gotcha Dear PyGui is *not entirely thread-safe*. While some improvements have been made, shared resources like `dpg.last_item()` or the container stack are still not synchronized across threads, which can lead to deadlocks, segfaults, or race conditions.
Fix: Avoid accessing or modifying DearPyGui items from multiple threads simultaneously. Perform all GUI-related operations exclusively on the main thread, or implement custom synchronization mechanisms for any cross-thread communication.
gotcha When using a custom rendering loop (e.g., `render_dearpygui_frame` instead of `start_dearpygui`) on Windows, the rendering frame can block during viewport resizing or movement. This can impact responsiveness, especially with `asyncio` in the main thread.
Fix: Be aware of this blocking behavior. If responsiveness during resize is critical, consider alternative ways to manage your main loop or structure your application to account for these pauses. For most simple applications, `start_dearpygui()` handles this implicitly.

Install

pip install dearpygui Install latest version

Imports

dpg
```
import dearpygui.dearpygui as dpg
```

Quickstart

This quickstart creates a simple DearPyGui application with a window containing text and a button. It demonstrates the basic lifecycle: context creation, viewport setup, running the main loop, and context destruction.

import dearpygui.dearpygui as dpg

dpg.create_context()
dpg.create_viewport(title='My DPG App', width=800, height=600)
dpg.setup_dearpygui()

with dpg.window(label="Example Window", width=200, height=200):
    dpg.add_text("Hello, DearPyGui!")
    dpg.add_button(label="Click Me", callback=lambda: print("Button Clicked!"))

dpg.show_viewport()
dpg.start_dearpygui()
dpg.destroy_context()

view raw JSON →