Installation

Pyzed requires Python 3.10 or later.

From PyPI

uv add pyzed-ui          # in a uv project
uv run python main.py

python3 -m venv .venv       # once per project
source .venv/bin/activate
pip install pyzed-ui
python main.py

py -m venv .venv       # once per project
.venv\Scripts\Activate.ps1
pip install pyzed-ui
python main.py

python3 -m pip install pyzed-ui
python3 main.py

py -m pip install pyzed-ui
py main.py

uv manages a project for you: Create a project starts a new app this way, and it is what the rest of these docs use. Install it from docs.astral.sh/uv.
pip installs into a virtual environment (.venv), a folder that keeps this project’s packages apart from the rest of your computer. Activate it in each new terminal before running your app.
python installs into the Python on your computer, with nothing else to learn. On Windows, py is the Python launcher that comes with the installer from python.org; on macOS and Linux the command is usually python3.

The package is called pyzed-ui on PyPI (the name pyzed was already taken), but it is imported as pyzed. The prebuilt wheels for Linux, macOS and Windows include the Rust engine, so you don’t need to compile anything.

From source

uv add git+https://github.com/albakore/pyzed

pip install git+https://github.com/albakore/pyzed     # with .venv active

python3 -m pip install git+https://github.com/albakore/pyzed

py -m pip install git+https://github.com/albakore/pyzed

This compiles the Rust extension, so you need Rust 1.88 or newer (rustup update upgrades an older one) and your platform’s system dependencies:

# Debian / Ubuntu
sudo apt install build-essential libxkbcommon-x11-0
curl https://sh.rustup.rs -sSf | sh

xcode-select --install
curl https://sh.rustup.rs -sSf | sh

Developing Pyzed

To work on Pyzed itself, clone the repository. You need Rust 1.88 or newer (rustup update upgrades an older one) and the system dependencies above.

git clone https://github.com/albakore/pyzed
cd pyzed
uv sync                          # creates .venv, builds the Rust core (release) and installs pyzed editable
uv run pytest tests
uv run python examples/gallery.py

git clone https://github.com/albakore/pyzed
cd pyzed
python3 -m venv .venv
source .venv/bin/activate
pip install maturin pytest
maturin develop --release        # run it again after changing Rust code
pytest tests
python examples/gallery.py

git clone https://github.com/albakore/pyzed
cd pyzed
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install maturin pytest
maturin develop --release        # run it again after changing Rust code
pytest tests
python examples/gallery.py

uv sync also installs the test group (maturin and pytest). The first build takes a few minutes.
Python changes under python/pyzed/ are picked up directly.
With uv, the next uv run or uv sync after changing Rust code (src/) rebuilds the core by itself; with pip, run maturin develop --release again. Use --release: the debug build is much slower when using the window.
uv sync --extra designer adds ty and ruff for the designer’s code editor.
On Linux a build from source plays no sound by default, so it builds without extra system packages: pyzed.audio renders offline and on its silent clock. For audio devices and MIDI, install ALSA’s headers (sudo apt install libasound2-dev pkg-config; Fedora: sudo dnf install alsa-lib-devel) and build with maturin develop --release --features alsa (with uv, keep MATURIN_PEP517_ARGS="--features alsa" exported and run uv sync --reinstall-package pyzed-ui).

Linux and WSL

Pyzed sets a few defaults before the first window opens:

GPU driver warnings are silenced. Mesa prints messages such as libEGL warning: failed to get driver name for fd -1 or MESA: error: ZINK: failed to choose pdev while the renderer looks for a working backend. They are harmless, so Pyzed sets EGL_LOG_LEVEL=fatal and MESA_LOG=null. Set PYZED_GPU_LOGS=1 to see them again.
WSL uses X11. The Wayland compositor of WSLg drops the connection when a window is maximized or resized, which prints Io error: Broken pipe (os error 32). Under WSL, Pyzed uses X11 (through XWayland) instead. Set PYZED_WAYLAND=1 to keep Wayland.
WSL opens pages in Windows’ browser. WSL usually has no browser of its own, so sign-ins (the AI agents’), the docs and other links open in your default Windows browser. Pages that call back to Pyzed on 127.0.0.1 still reach it through WSL’s localhost forwarding. Programs that need a terminal, such as the Claude Code sign-in, open in Windows Terminal (or a console) back in your WSL distribution. Set BROWSER to pick a browser yourself.

Variables you set yourself (EGL_LOG_LEVEL, MESA_LOG, WAYLAND_DISPLAY, BROWSER…) are never changed.

WSL: native Windows windows

Under WSL, Pyzed opens every window as a native Windows program, not through WSLg: pyzed design, pyzed run, pyzed dev, your scripts that call pz.run, Run in Pyzed Design and the AI agents’ live previews. The window is a real Windows window, drawn with Windows’ own GPU drivers, so it is faster and snaps, scales and shows in the taskbar like any other app. Your code and your project stay in WSL: you keep editing in Linux (in Zed, for example), and hot reload picks up every save.

All it needs is uv on Windows. Pyzed can install it for you, from WSL:

uv run pyzed windows setup     # installs uv on Windows if it is missing and prepares the project
uv run pyzed windows           # shows what is used and where

How it works:

Windows reads the project through \\wsl.localhost\<distribution>\... and starts in the same folder.
Windows gets its own environment, in %LOCALAPPDATA%\pyzed\wsl\, with the same Python version, the project’s dependencies at the versions of uv.lock, what the editor needs (AI agents, MCP, language servers) and the pyzed-ui wheel of the same version (always a prebuilt wheel: nothing is compiled on Windows). The project’s .venv stays the Linux one. It is made the first time (a few seconds) and again only when the dependencies change.
The command in WSL waits for the window: its output, the console of Pyzed Design and the exit code are the app’s, and stopping it (Stop, Ctrl+C) closes the window.

Without uv (or Python’s py launcher) on Windows, windows open through WSLg as before, with a note on how to set it up. To always use WSLg, set PYZED_WINDOWS=0 or add --wslg to pyzed design, run or dev.

Variable	What it does
`PYZED_WINDOWS=0`	Opens windows through WSLg.
`PYZED_WINDOWS_ENV=NAME,NAME`	More variables for the app on Windows (API keys…). `PYZED_*` ones always cross.
`PYZED_WINDOWS_WHEEL`	Path or URL of the `pyzed-ui` wheel for Windows (see below).
`PYZED_WINDOWS_TARGET`	Rust target for a checkout’s core (`x86_64-pc-windows-gnu` or `-msvc`).

From a checkout of Pyzed (uv sync in the repository), Windows runs your checkout: its Python files are imported from WSL, so every change shows up, and its Rust core is cross-compiled for Windows in WSL, once per change to the Rust sources (the first build takes a few minutes; nothing is compiled on Windows). It needs a cross compiler, installed once:

sudo apt install mingw-w64     # or clang and lld, for the MSVC target of the released wheels

Without one, windows open through WSLg with a note saying so. PYZED_WINDOWS_WHEEL (the path or URL of a Windows wheel) skips the build, and PYZED_WINDOWS_TARGET picks the Rust target.

When Pyzed Design runs on Windows this way, everything it starts runs on Windows too: Run, the project’s script, previews and audio use Windows’ devices. Creating or cloning a project in a WSL folder uses Linux’s uv and git, so the project and its .venv stay Linux ones.

Verify the installation

uv run python -c "import pyzed; print(pyzed.__version__)"
uv run pyzed icons folder

python -c "import pyzed; print(pyzed.__version__)"
pyzed icons folder

python3 -c "import pyzed; print(pyzed.__version__)"
python3 -m pyzed icons folder

py -c "import pyzed; print(pyzed.__version__)"
py -m pyzed icons folder

The first line prints the version; the second lists the icon names that contain “folder”.