Requirements:
- CMake ≥ 3.20
- A C11 / C++20 compiler: GCC (MinGW-w64 on Windows), Clang or MSVC
- Python 3.11+ with development headers, for the Python APIs (
buipy) - On Linux, the X11 headers (
libx11-dev/libX11-devel) for native windows. No GL headers are needed.
cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failureOn Windows with MSYS2 / MinGW-w64:
cmake -S . -B build -G "MinGW Makefiles"
cmake --build build| Option | Default | Effect |
|---|---|---|
BUI_BUILD_PYTHON_BINDINGS |
ON |
Build the buipy CPython extension. It is skipped with a message if the Python dev files are missing. |
BUI_BUILD_LUA_BINDINGS |
OFF |
The Lua 5.4 host (bui-lua and the bui module). Lua is fetched at configure time when the system has no Lua 5.4. |
BUI_BUILD_TESTS |
ON |
C test executables and the ctest suites |
BUI_BUILD_EXAMPLES |
OFF |
C examples (bui_kit_hello, bui_svg_demo, the site screenshot programs) |
BUI_BUILD_UI |
OFF |
Compile Blender's original ui/ sources as well (not needed for the kit) |
BUI_BUILD_QT_BACKEND |
OFF |
The C++ Qt/QPainter render-sink backend (needs Qt 5/6 Widgets) |
BUI_BUILD_IMGUI |
ON when a C++ compiler is present |
Dear ImGui on BUI (bui::imgui), its C API (bui_cimgui), demo and test |
BUI_IMGUI_BLENDER_WIDGETS |
OFF |
Dear ImGui's widgets become Blender's (an edited imgui_widgets.cpp) |
BUI_WARNINGS_AS_ERRORS |
OFF |
Only affects GCC and Clang today: when OFF the build adds -Wno-error; when ON it doesn't. It never adds -Werror or /WX by itself. |
BUI_SLUG |
ON |
GPU text from glyph outlines (Slug) by default; OFF makes the glyph atlas the default (switchable at run time either way) |
BUI_IMAGE_SVG |
ON |
SVG images through the kit's nanosvg (no extra code: Blender's icons use it already) |
BUI_TEXT_FREETYPE |
ON |
Rasterize glyphs with the vendored FreeType 2.13.3, the way Blender's BLF does (light hinting, gamma 1.43, Inter's optical size). OFF uses stb_truetype. Ignored when BUI_TEXT_GDI is on. |
BUI_TEXT_GDI |
OFF |
Use Windows' GDI text engine and system fonts instead of the portable engine (embedded Inter, Slug on the GPU) |
The pure-Python package is bindings/python/bui. Put that directory on the
path:
export PYTHONPATH=/path/to/BUI/bindings/python # Windows: set PYTHONPATH=C:\path\to\BUI\bindings\pythonimport bui (and anything under it) finds the compiled buipy extension
in your CMake build directory by itself (build*/bindings/python/). If you
keep the build somewhere else, point to it:
export BUIPY_BUILD_DIR=/path/to/build/bindings/pythonCheck the setup:
python -c "import bui, buipy; print(buipy.kit_window_supported(), len(buipy.kit_icon_names()))"
python examples/components_demo.py
python -m bui.tksyntax examples/tk_unchanged_app.py
python examples/qt_syntax_demo.py| You have / want | Use | Guide |
|---|---|---|
| An existing tkinter app | python -m bui.tksyntax app.py, or bui.tksyntax.install() |
tkinter.md |
| New code, tkinter style | import bui.tksyntax as tk |
tkinter.md |
| Qt-style code | from bui.qtsyntax import ... |
qt.md |
| A Blender-like tool panel | from bui.components import ... |
components.md |
| BUI drawing inside your own renderer | Render sinks | ../INTEGRATION.md |
| C only | kit/include/BUI_kit.h |
c-api.md |
You can mix them in one process. Windows, timers and the event loop are
shared (bui.host).
| Variable | Effect |
|---|---|
BUIPY_BUILD_DIR |
Directory containing the built buipy extension |
BUI_HOST=tk |
Force the stdlib-Tk window host even where the native host exists |
BUI_UI_SCALE |
Fix the UI scale (for example 1.5) instead of following the monitor's DPI |
BUI_GPU=1 |
Draw native windows on the GPU (Direct3D 11 on Windows, OpenGL 3.3 on Linux). Overrides the app-wide defaults bui.set_gpu(), Application::gpu() and BUI_gpu_set_default(). BUI_GPU=0 turns those defaults off, but a window that asks for the GPU itself (Tk(gpu=True), WindowOptions { gpu: Some(true) }, BK_window_set_gpu) still gets it. |
BUI_GPU_DEBUG=1 |
Print why the GPU renderer could not start |
BUI_FONT, BUI_FONT_DIR |
A font file to replace the embedded Inter UI font, and an extra font folder |
BUI_SLUG |
0 draws GPU text from a per-glyph bitmap atlas instead of glyph outlines (Slug); 1 forces Slug. Overrides bui.set_slug() / .slug() / BUI_gpu_set_slug() |
BUI_PROFILE |
Print frame times every 60 frames (per phase in Rust and JavaScript; raster and present in the Windows host). Any value turns it on, even 0. |
BUI_THEME |
dark (default) or light: Blender's Dark or Light theme preset, when the app doesn't call bui.set_theme() / blenderui::set_theme() / BK_set_theme() |
BUI_FILEDIALOG=native (or system, tk) |
File dialogs (tkinter.filedialog, QFileDialog) use the operating system's dialogs instead of Blender's File Browser |
BUI_BOOKMARKS |
The file browser's bookmarks file (default $XDG_CONFIG_HOME/bui/bookmarks.txt, or %APPDATA%\bui\bookmarks.txt on Windows) |
bui.host.Window puts a kit context in a top-level window.
- Native (Windows and Linux). A window written in C: BUI's own Win32 host on Windows,
X11 on Linux (and an experimental native Wayland host; X11 also runs through XWayland). Input goes
straight into the kit, and frames are presented by blitting only the
changed tiles. It follows the display's DPI (per-monitor on Windows,
Xft.dpion X11) and paces animations to the display's refresh rate. - Native (macOS). A Cocoa window (a port of Blender's GHOST code; checked by CI and tried by hand on three Macs (two Apple Silicon, one Intel)) with Retina scaling. It needs the main thread. See macos-testing.md.
- Tk (with
BUI_HOST=tk, or where no native host works). A stdlibtkinterwindow that shows the kit's frame buffer and forwards input to it. The UI and the API are identical, but presenting is a little slower.
Native windows draw on the CPU by default. To draw them on the GPU (Direct3D 11 on Windows, OpenGL 3.3 on Linux) instead, use one of these:
| Where | Flag |
|---|---|
| tkinter syntax | tk.Tk(gpu=True) |
| Any Python API | bui.set_gpu(True) before creating windows |
| Rust | Application::new().gpu(true) or WindowOptions { gpu: Some(true), .. } |
| C | BUI_gpu_set_default(1) or BK_window_set_gpu(win, 1) |
| Any app, no code change | BUI_GPU=1 |
GPU text is drawn with Slug (from glyph outlines, sharp at any size) or from a per-glyph bitmap atlas like Blender's (about half the GPU work):
| Where | Slug (default) / atlas |
|---|---|
| Python | bui.set_slug(True) / bui.set_slug(False) |
| Rust | Application::new().slug(..), blenderui::set_slug(..), or build without the default slug feature |
| C | BUI_gpu_set_slug(1 / 0), or CMake -DBUI_SLUG=OFF for the atlas by default |
| Any app | BUI_SLUG=1 / BUI_SLUG=0 |
Both renderers draw the same pixels. The GPU uses far less CPU per frame (about 2-4x less in the benchmark), but the process needs about 10 MB more RAM plus GPU memory. The device starts in the background, so the first frames are drawn on the CPU and the switch happens a few frames in. The GPU renderer is Direct3D 11 on Windows and OpenGL 3.3 on Linux (libGL is loaded at run time). Without a GPU or OpenGL, and on macOS, windows stay on the software raster.
bui.host.run() runs one loop for all windows, bui.host.update() processes
pending events once, and bui.host.quit() stops the loop.
| Symptom | Fix |
|---|---|
ImportError: buipy |
Build first (cmake --build build) or set BUIPY_BUILD_DIR. The extension must match your Python version: a cp314 build needs Python 3.14. |
| Window doesn't appear | Call mainloop() / app.exec() / App.run(). Without a loop, windows only show during update(). |
| Blurry or tiny UI | Set BUI_UI_SCALE. On Windows the native host is DPI-aware by default. |
gpu=True has no effect |
Run with BUI_GPU_DEBUG=1 to see why the device failed. Machines without Direct3D 11 (Windows) or OpenGL 3.3 (Linux) stay on the software raster. |
| Monospace/serif text uses the UI font | Install a TrueType font family (DejaVu, Liberation or Noto). The UI font itself (Inter) is embedded. |
| A tkinter feature behaves differently | See the behaviour notes in tkinter.md. If stdlib tkinter does something else, that is a bug; bindings/python/tests/test_tk_compat.py shows how to write a side-by-side check. |