# Installation

> Install Pyzed with pip or uv on Windows, macOS and Linux. Prebuilt wheels include the Rust engine, so Python 3.10+ is all you need to start.

Source: https://albakore.github.io/pyzed/getting-started/installation/

Pyzed requires **Python 3.10 or later**.

## From PyPI

- **uv** manages a project for you: [Create a project](https://albakore.github.io/pyzed/getting-started/new-project/) starts a new app this
  way, and it is what the rest of these docs use. Install it from [docs.astral.sh/uv](https://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](https://www.python.org/downloads/); 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.

**Only prebuilt wheels:**

PyPI only has wheels, built and tested by the release pipeline for Linux (x86_64 and ARM, glibc and musl),
macOS (Intel and Apple Silicon) and Windows (x64 and ARM). One wheel covers every Python from 3.10. On any
other platform the install stops with an error instead of compiling; install from source (below) there.

## From source

This compiles the Rust extension, so you need [Rust 1.88 or newer](https://rustup.rs) (`rustup update` upgrades an older one) and your
platform's system dependencies:

**Linux:**

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

**macOS:**

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

**Windows:**

Install [Rust with rustup](https://rustup.rs) and the *Build Tools for Visual Studio*
("Desktop development with C++" workload).

## Developing Pyzed

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

- `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](https://docs.astral.sh/uv/getting-started/installation/). Pyzed can install it
for you, from WSL:

```bash
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, <kbd>Ctrl</kbd>+<kbd>C</kbd>) 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`). |

:::note[Working on Pyzed itself]
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:

```bash
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

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