Python Dear PyGui — Core Concepts

Understand the immediate-mode rendering model, item hierarchy, and callback system that make Dear PyGui the fastest way to build GPU-accelerated Python tool UIs.

What Dear PyGui is

Dear PyGui (DPG) is a GPU-accelerated GUI framework for Python, built on top of Dear ImGui — the immediate-mode GUI library widely used in game engines, 3D tools, and debug interfaces. Unlike Tkinter or PyQt, which use OS-native or styled widgets, DPG renders everything through DirectX (Windows), Metal (macOS), or Vulkan/OpenGL (Linux), producing smooth 60fps interfaces.

Retained mode with an immediate-mode core

Dear ImGui is “immediate mode” — you redraw the UI every frame. DPG wraps this in a retained mode API where you create items once and they persist:

import dearpygui.dearpygui as dpg

dpg.create_context()

with dpg.window(label="Settings", width=400, height=300):
    dpg.add_text("Adjust parameters:")
    dpg.add_slider_float(label="Learning Rate", default_value=0.01,
                         min_value=0.001, max_value=1.0,
                         callback=lambda s, val: print(f"LR: {val}"))
    dpg.add_color_picker(label="Background Color")
    dpg.add_checkbox(label="Enable Logging", default_value=True)

dpg.create_viewport(title="ML Dashboard", width=800, height=600)
dpg.setup_dearpygui()
dpg.show_viewport()
dpg.start_dearpygui()
dpg.destroy_context()

You create items with dpg.add_*, and DPG handles redrawing them each frame automatically.

Item hierarchy

DPG uses a tree of items identified by integer tags (or auto-generated IDs):

Viewport — the OS window
Window — a draggable panel inside the viewport
Groups/Child Windows — containers for layout
Items — buttons, sliders, inputs, plots, tables, etc.

Items are added as children of their container. You can show, hide, move, or delete any item by its tag at any time.

Callbacks and state

Widgets that accept user input take a callback parameter:

def on_submit(sender, app_data, user_data):
    name = dpg.get_value(sender)
    print(f"Submitted: {name}")

dpg.add_input_text(label="Name", callback=on_submit, on_enter=True)

Every callback receives three arguments:

sender — the tag of the widget that triggered the event
app_data — the current value
user_data — optional custom data you attached

Read any widget’s value with dpg.get_value(tag) and set it with dpg.set_value(tag, new_value).

Built-in plotting

DPG includes a fast plotting library (wrapping ImPlot):

import math

x = [i * 0.1 for i in range(100)]
y_sin = [math.sin(v) for v in x]
y_cos = [math.cos(v) for v in x]

with dpg.window(label="Charts"):
    with dpg.plot(label="Trig Functions", height=300, width=-1):
        dpg.add_plot_legend()
        dpg.add_plot_axis(dpg.mvXAxis, label="x")
        with dpg.plot_axis(dpg.mvYAxis, label="y"):
            dpg.add_line_series(x, y_sin, label="sin(x)")
            dpg.add_line_series(x, y_cos, label="cos(x)")

Plots support line, scatter, bar, heatmap, pie, and candlestick series. Data updates at 60fps, making live dashboards smooth.

Tables and data grids

with dpg.table(header_row=True, resizable=True, sortable=True):
    dpg.add_table_column(label="Name")
    dpg.add_table_column(label="Score")
    dpg.add_table_column(label="Status")

    for name, score, status in data:
        with dpg.table_row():
            dpg.add_text(name)
            dpg.add_text(str(score))
            dpg.add_text(status)

Tables support column resizing, sorting callbacks, and row clipping for performance.

Theming

DPG provides a theming system that controls colors, rounding, padding, and spacing:

with dpg.theme() as dark_theme:
    with dpg.theme_component(dpg.mvAll):
        dpg.add_theme_color(dpg.mvThemeCol_WindowBg, (30, 30, 30))
        dpg.add_theme_color(dpg.mvThemeCol_Button, (50, 100, 200))
        dpg.add_theme_style(dpg.mvStyleVar_FrameRounding, 5)

dpg.bind_theme(dark_theme)

Themes can be global or bound to specific items for mixed styling.

Common misconception

“Dear PyGui is just for games and demos.”

While its roots are in game tooling, DPG is increasingly used for ML experiment dashboards, audio/video processing tools, robotics control panels, and hardware testing interfaces — anywhere a standard GUI feels too slow or too rigid for real-time data display.

When to choose Dear PyGui

DPG excels at developer tools, dashboards with live-updating charts, and parameter tuning interfaces. It is less suited for document-oriented apps (word processors, email clients) or apps that need OS-native look and feel. For those, PyQt or Tkinter are better choices.

One thing to remember: Dear PyGui fills the gap between simple Tkinter scripts and full PyQt applications — it gives you GPU-accelerated rendering with a simple API, making real-time dashboards and interactive tools trivially easy.

pythondear-pyguiguigpuimgui