Setting Up Your GPUI Development Environment (2026-05-24)

Welcome to the exciting world of GPUI, the GPU-accelerated UI framework powering the Zed editor! If you’re a Rust developer looking to build high-performance, native user interfaces on macOS or Linux, you’ve come to the right place. GPUI offers a unique hybrid rendering model that promises exceptional speed and responsiveness, making it ideal for demanding applications.

In this chapter, we’ll guide you through setting up your development environment, understanding GPUI’s fundamental design principles, and creating your very first GPUI application. We’ll emphasize practical, step-by-step instructions, ensuring you grasp not just how to set things up, but why each piece is important.

Important Note: GPUI is in active development, meaning its APIs are subject to frequent changes and refinements. This guide reflects the state of GPUI as of 2026-05-24, primarily referencing the main branch of the zed-industries/zed repository. We’ll highlight where to look for the most up-to-date information directly from the source.

Why GPUI Matters: Performance and Control

GPUI exists to solve a critical problem in UI development: achieving native-level performance and responsiveness without sacrificing the flexibility of modern declarative UI paradigms. Traditional UI frameworks often struggle with high frame rates or complex custom rendering without significant effort.

GPUI addresses this by taking a “hybrid” approach to rendering. It leverages the GPU directly for drawing, bypassing many layers of abstraction found in other frameworks. This means your UI can update extremely quickly, even with complex animations or large amounts of data. For applications like code editors, data visualization tools, or real-time dashboards, this performance edge is invaluable.

Core Concepts: GPUI’s Foundational Principles

Before we dive into setup, let’s understand some core ideas that make GPUI unique. Understanding these principles will make navigating GPUI’s active development much easier.

Hybrid Immediate and Retained Mode Rendering

This is GPUI’s superpower and a key differentiator. 🧠 Important: Most UI frameworks choose one rendering mode. GPUI blends them for optimal performance and developer experience.

Immediate Mode: Imagine telling the computer, “Draw a circle here, then a square there, then some text.” Every frame, you issue all drawing commands from scratch. This is simple to implement but can be inefficient if not managed carefully, as it redraws everything, even static parts.
Retained Mode: Here, you describe your UI components once, and the framework builds a “scene graph” (a tree of UI elements). It then intelligently figures out what changed between frames and only redraws the affected parts. This is efficient but can make state management and dynamic UI updates more complex for the developer.

GPUI cleverly combines both strengths. You, as the developer, define your UI declaratively using elements and views (like a retained mode). However, under the hood, GPUI efficiently translates this description into optimized GPU commands each frame (leveraging immediate mode’s directness). This hybrid model gives developers a productive, declarative API while ensuring the underlying rendering is blazing fast and GPU-accelerated.

Active Development: Learning from the Source

GPUI is the engine of the Zed editor, a project known for its rapid innovation and cutting-edge performance. This means:

Unstable APIs: Expect APIs to evolve. What works today might change tomorrow as the framework matures. This is a common characteristic of bleeding-edge projects.
Limited Standalone Documentation: The primary source of truth is often the Zed editor’s own codebase, specifically the crates/gpui directory within the main Zed repository.
Best Practice: When in doubt, look at how Zed itself uses GPUI. This is the most reliable way to understand current patterns and best practices. The Zed editor is a complex, production-ready application built entirely with GPUI, making its source code an invaluable learning resource. ⚡ Real-world insight: Think of the Zed editor as the ultimate GPUI example project. Its source code demonstrates advanced usage, performance optimizations, and current API patterns.

System Requirements

To develop with GPUI, you’ll need:

Operating System: macOS (Intel or Apple Silicon) or Linux. Windows is not officially supported by GPUI itself at this time.
Rust Toolchain: A stable Rust toolchain installed via rustup.

Step-by-Step Implementation: Your First GPUI Project

Let’s get your development environment ready and build a simple “Hello, GPUI!” application.

1. Install the Rust Toolchain

If you don’t already have Rust installed, rustup is the official and recommended way. Open your terminal and run the following command to begin the installation:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Follow the on-screen instructions. Typically, you’ll choose option 1 for a default installation. Once the installation completes, you’ll likely need to restart your terminal or source your shell’s profile (source ~/.bashrc, source ~/.zshrc, etc.) to update your PATH.

Verify your installation by checking the versions of rustc (the Rust compiler) and cargo (the Rust package manager and build tool):

rustc --version
cargo --version

As of 2026-05-24, you should see a recent stable version, for example: rustc 1.8X.0 (some-hash 2026-XX-XX).

2. Create a New Rust Project

Next, we’ll create a new Rust binary project. Navigate to your desired development directory in your terminal and run:

cargo new my-gpui-app --bin
cd my-gpui-app

Explanation:

cargo new my-gpui-app --bin: This command initializes a new Rust project named my-gpui-app. The --bin flag specifies that it’s an executable application (a binary), not a library.
cd my-gpui-app: This changes your current directory into the newly created project folder.

Inside my-gpui-app, you’ll find a Cargo.toml file (the project manifest) and a src directory containing main.rs (your main source code file).

3. Add GPUI as a Dependency

Now, we need to tell Rust that our project depends on GPUI. Since GPUI is under active development and not yet published as a stable crate on crates.io, we’ll pull it directly from the Zed GitHub repository’s main branch.

Open your Cargo.toml file (located in the my-gpui-app directory) and add the following under the [dependencies] section. If [dependencies] isn’t there, add it.

# Cargo.toml
[package]
name = "my-gpui-app"
version = "0.1.0"
edition = "2021"

[dependencies]
gpui = { git = "https://github.com/zed-industries/zed.git", branch = "main", package = "gpui" }

Explanation:

gpui = { ... }: This line declares gpui as a dependency for your project.
git = "https://github.com/zed-industries/zed.git": We’re sourcing this dependency directly from the official Zed GitHub repository.
branch = "main": We’re specifically targeting the main branch. This ensures you’re using the absolute latest code, but also means you’re exposed to potential breaking changes.
package = "gpui": The Zed repository is a monorepo, meaning it contains multiple Rust crates. This line specifies that we want to use the gpui crate from within that larger repository.

4. Install System Dependencies (Linux Only)

If you are on Linux, GPUI (which relies on winit and other underlying libraries for windowing and display management) may require certain system packages. These packages provide the necessary development headers and libraries. While specific requirements can vary by distribution, common ones include:

For Debian/Ubuntu-based systems:

sudo apt update
sudo apt install libxkbcommon-dev libwayland-dev libfontconfig-dev libdbus-1-dev

For Fedora-based systems:

sudo dnf install libxkbcommon-devel wayland-devel fontconfig-devel dbus-devel

⚠️ What can go wrong: If you encounter compilation errors related to missing pkg-config entries for libraries like xkbcommon, wayland, or fontconfig during cargo run, it’s highly likely you need to install these system-level development packages. macOS typically has these dependencies pre-installed or handles them automatically.

5. Write Your First GPUI Application

Now for the fun part! Let’s write the minimal “Hello, GPUI!” application. Open the src/main.rs file within your my-gpui-app directory.

First, clear any existing content in main.rs and add the necessary use statements. These lines bring specific types and functions from the gpui crate into our program’s scope, making them directly accessible.

// src/main.rs
use gpui::{
    elements::*, App, AppContext, Render, View, ViewContext, WindowOptions,
};

Explanation of use statements:

elements::*: This imports all public items from the elements module. This module contains fundamental UI building blocks like div, text, button, etc., which you’ll use to compose your user interface.
App: Represents the main application instance. It’s your program’s entry point into the GPUI world.
AppContext: Provides access to global application-level services, state, and allows you to manage windows.
Render: A trait that your UI components (Views) must implement to describe how they draw themselves on the screen.
View: A trait that defines a reusable UI component that can hold state and interact with the application.
ViewContext: Provides access to services and state specific to a particular view instance.
WindowOptions: A struct used to configure properties when opening a new window (e.g., title, size).

Next, let’s define our first UI component, HelloView. In GPUI, UI components are typically Rust structs that implement the View trait. For now, our HelloView will be a simple, empty struct.

// src/main.rs - continued
// ... (use statements)

struct HelloView;

Now, we need to tell GPUI that HelloView is indeed a View. We do this by implementing the View trait for our struct.

// src/main.rs - continued
// ... (HelloView struct)

impl View for HelloView {
    fn ui_name() -> &'static str {
        "HelloView"
    }
}

Explanation:

impl View for HelloView: This block implements the View trait for our HelloView struct.
fn ui_name() -> &'static str: The View trait requires a ui_name method. This returns a static string that uniquely identifies the type of view. It’s helpful for debugging and introspection within GPUI’s developer tools.

Our HelloView now exists, but it doesn’t do anything visually. To make it draw something, it needs to implement the Render trait. The render method is where you declaratively describe your UI using GPUI’s element builders.

Let’s add the Render implementation step-by-step:

// src/main.rs - continued
// ... (HelloView struct and impl View)

impl Render for HelloView {
    fn render(&mut self, _cx: &mut ViewContext<Self>) -> Element {
        // We'll build our UI here
        // ...
    }
}

Explanation:

impl Render for HelloView: This block implements the Render trait for HelloView.
fn render(&mut self, _cx: &mut ViewContext<Self>) -> Element: This is the core method of the Render trait.
- &mut self: A mutable reference to our HelloView instance.
- _cx: &mut ViewContext<Self>: A mutable ViewContext specific to this view. It’s currently unused (hence the _), but it’s crucial for interacting with the view’s state and performing actions later.
- -> Element: The method must return an Element, which is GPUI’s abstract representation of a UI component.

Now, let’s fill in the render method to display “Hello, GPUI!” with some basic styling. We’ll build this element tree incrementally.

First, let’s create a div element. Think of div() as the most basic container, similar to an HTML <div>.

// src/main.rs - inside impl Render for HelloView
// ...
impl Render for HelloView {
    fn render(&mut self, _cx: &mut ViewContext<Self>) -> Element {
        div() // Our root container element
        // ... more elements and styling will go here
    }
}

Next, let’s give our div some styling: white text color and a dark gray background. GPUI uses a chainable API for styling, making it very fluent.

// src/main.rs - inside impl Render for HelloView
// ...
impl Render for HelloView {
    fn render(&mut self, _cx: &mut ViewContext<Self>) -> Element {
        div()
            .text_color(gpui::rgb(0xFFFFFF)) // Set text color to white
            .bg(gpui::rgb(0x333333))         // Set background color to dark gray
        // ... more elements and styling
    }
}

Explanation:

.text_color(gpui::rgb(0xFFFFFF)): Sets the color of any text within this div (or its children) to white. gpui::rgb is a helper function to create a color from a hexadecimal RGB value.
.bg(gpui::rgb(0x333333)): Sets the background color of the div itself to a dark gray.

Let’s add some padding around our content. GPUI often uses a utility-first approach for layout, similar to Tailwind CSS.

// src/main.rs - inside impl Render for HelloView
// ...
impl Render for HelloView {
    fn render(&mut self, _cx: &mut ViewContext<Self>) -> Element {
        div()
            .text_color(gpui::rgb(0xFFFFFF))
            .bg(gpui::rgb(0x333333))
            .p_4()                           // Apply 4 units of padding on all sides
        // ... more elements and styling
    }
}

Explanation:

.p_4(): This method applies padding of 4 units (GPUI’s internal spacing unit) to all sides of the div. Other methods like px_4() (horizontal padding) or pt_4() (top padding) also exist.

Now, let’s add the actual “Hello, GPUI!” text as a child of our div.

// src/main.rs - inside impl Render for HelloView
// ...
impl Render for HelloView {
    fn render(&mut self, _cx: &mut ViewContext<Self>) -> Element {
        div()
            .text_color(gpui::rgb(0xFFFFFF))
            .bg(gpui::rgb(0x333333))
            .p_4()
            .child(text("Hello, GPUI!"))     // Add a text element as a child
        // ... almost done!
    }
}

Explanation:

.child(text("Hello, GPUI!")): This method adds another Element as a child of the current div. Here, we’re creating a text element with the string “Hello, GPUI!” and making it a child.

Finally, the render method must return a generic Element. Our div builder returns a specific Div element, so we need to convert it.

// src/main.rs - inside impl Render for HelloView
// ...
impl Render for HelloView {
    fn render(&mut self, _cx: &mut ViewContext<Self>) -> Element {
        div()
            .text_color(gpui::rgb(0xFFFFFF))
            .bg(gpui::rgb(0x333333))
            .p_4()
            .child(text("Hello, GPUI!"))
            .into_any_element()              // Convert our specific Div element into a generic Element
    }
}

Explanation:

.into_any_element(): This is a common pattern in GPUI. It converts a concrete element type (like Div) into the more general Element trait object, allowing it to be returned from render.

Finally, let’s put it all together in our main function to launch the application. This is the entry point of your Rust program and where you initialize and run the GPUI App.

// src/main.rs - continued
// ... (all previous code: use statements, HelloView struct, impl View, impl Render)

fn main() {
    App::new() // 1. Create a new GPUI application instance
        .run(|cx: &mut AppContext| { // 2. Start the application event loop
            // 3. Open a new window with default options
            cx.open_window(WindowOptions::default(), |cx| {
                // 4. Create an instance of our HelloView and add it as the window's root view
                cx.new_view(|_cx| HelloView)
            });
        });
}

Explanation:

fn main(): The standard entry point for any Rust executable.
App::new(): This static method creates a new instance of the GPUI application. This is the first step in any GPUI program.
.run(|cx: &mut AppContext| { ... }): This method starts the GPUI event loop. The closure provided to run is executed once the application starts. It receives an AppContext, which is your primary interface for application-wide operations, like opening windows.
cx.open_window(WindowOptions::default(), |cx| { ... }): This method tells the AppContext to open a new window.
- WindowOptions::default(): We’re using the default window configuration (e.g., default size, title, etc.). You can customize this later.
- The inner closure is executed when the window is ready. It receives a ViewContext (or similar, specific to the window’s root view) which is used to create the initial UI content for that window.
cx.new_view(|_cx| HelloView): Inside the window’s context, we use new_view to create an instance of our HelloView and set it as the root view of this new window. GPUI takes ownership and manages the lifecycle of this view.

6. Run Your Application

Save your src/main.rs file. Now, open your terminal in the my-gpui-app directory and run:

cargo run

Cargo will download GPUI and its dependencies (this might take a few minutes the first time), compile your application, and if all goes well, a new window should appear on your screen displaying “Hello, GPUI!” in white text on a dark gray background.

If you encounter compilation errors, double-check your Cargo.toml and src/main.rs for typos, and ensure you’ve installed any necessary system dependencies on Linux.

Here’s a visual representation of the setup flow:

flowchart TD Setup[Setup Rust Project] --> LinuxCheck{Linux User}; LinuxCheck -->|Yes| InstallDeps[Install System Dependencies]; LinuxCheck -->|No| Develop[Write GPUI Application]; InstallDeps --> Develop; Develop --> RunVerify[Run and Verify Application];

Mini-Challenge: Personalize Your Greeting

You’ve successfully launched your first GPUI app! Now, let’s make a small modification to solidify your understanding of basic elements and styling.

Challenge: Change the “Hello, GPUI!” text to display your name (e.g., “Hello, [Your Name]!”). Also, try changing the background color of the div to a different shade, perhaps a lighter gray (0x555555) or a soft blue (0x4A90E2).

Hint: Remember the text() and bg() methods in the render function. You can find many more color functions in the gpui crate, or just experiment with different rgb hexadecimal values!

What to Observe/Learn: This exercise reinforces how the render function describes your UI and how small changes in the Element chain directly affect the visual output. It also demonstrates the immediate feedback loop of GPUI development – make a change, recompile, and see the result.

Common Pitfalls & Troubleshooting

Working with an actively developed framework like GPUI can have its quirks. Here are some common issues you might encounter:

Frequent API Changes:
- Symptom: Your code that compiled and worked yesterday suddenly doesn’t compile after cargo update or pulling from the main branch.
- Solution: This is the most common challenge when using a rapidly evolving framework. 🧠 Important: Always be prepared to adapt your code. This is the trade-off for using a cutting-edge, high-performance framework.
  - Check the zed-industries/zed repository’s crates/gpui directory. Look at recent commits, specifically the src/lib.rs and examples within the gpui crate.
  - The Zed editor’s own source code (especially how it uses GPUI) is your ultimate reference for current patterns.
  - Look for official announcements or discussions in the Zed community if you’re stuck on a major breaking change.
Missing System Dependencies (Linux):
- Symptom: Compilation errors related to winit, xkbcommon, wayland, or fontconfig on Linux, often manifesting as pkg-config errors or “library not found.”
- Solution: Ensure you’ve installed the necessary development packages for your distribution (e.g., libxkbcommon-dev, libwayland-dev, libfontconfig-dev, libdbus-1-dev on Debian/Ubuntu). These provide the underlying system libraries GPUI needs for windowing, input, and rendering.
Complex Rust Compiler Error Messages:
- Symptom: Rust’s compiler errors can sometimes be long and intimidating, especially with generics and trait bounds used heavily in UI frameworks.
- Solution: Read them carefully. The compiler often points to the exact line and suggests fixes. Use cargo check frequently to catch errors early. Don’t be afraid to eprintln! or use dbg! to print values and debug your program’s state. Break down complex expressions into smaller parts to isolate the error.
cargo update Introducing Breaking Changes:
- Symptom: Running cargo update pulls in a new version of GPUI from main that introduces breaking changes, causing your project to fail to compile or behave unexpectedly.
- Solution: If you require more stability for a specific project, consider pinning to a specific commit hash in your Cargo.toml instead of branch = "main". For example:
```
gpui = { git = "https://github.com/zed-industries/zed.git", rev = "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0", package = "gpui" }
```
  Replace the rev with a specific commit hash you know works. This provides a snapshot, but you’ll miss out on new features and bug fixes unless you manually update the rev periodically. For learning, sticking to main is generally recommended to follow the latest developments.

Summary

In this chapter, you’ve taken the crucial first steps into GPUI development:

Understood GPUI’s Purpose: Learned why GPUI exists—to provide a high-performance, GPU-accelerated UI framework for macOS/Linux, leveraging a unique hybrid rendering model.
Acknowledged Active Development: You’re aware that GPUI’s APIs are unstable and that the Zed editor’s source code is your best friend for up-to-date patterns and examples.
Set Up Your Environment: Successfully installed the Rust toolchain, created a new Rust project, and added GPUI as a git dependency from the zed-industries/zed repository.
Built Your First App: Created a minimal “Hello, GPUI!” application, introducing core concepts like App, View, Render, Elements (like div and text), and basic styling (text_color, bg, p_4).
Explored Common Pitfalls: Gained insight into potential challenges such as API instability, missing system dependencies on Linux, and troubleshooting strategies.

You now have a functional GPUI development environment! In the next chapter, we’ll dive deeper into GPUI’s building blocks, exploring how to create more complex views, manage state, and introduce interactivity. Get ready to build more dynamic user interfaces!

References

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.

Setting Up Your GPUI Development Environment (2026-05-24)

// table of contents