Instalación

Pyzed necesita Python 3.10 o superior.

Desde PyPI

uv add pyzed-ui          # en un proyecto de uv
uv run python main.py

python3 -m venv .venv       # una vez por proyecto
source .venv/bin/activate
pip install pyzed-ui
python main.py

py -m venv .venv       # una vez por proyecto
.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 gestiona el proyecto por ti: Crear un proyecto empieza una app nueva así, y es lo que usa el resto de esta documentación. Instálalo desde docs.astral.sh/uv.
pip instala en un entorno virtual (.venv), una carpeta que separa los paquetes de este proyecto del resto de tu equipo. Actívalo en cada terminal nueva antes de ejecutar tu app.
python instala en el Python de tu equipo, sin nada más que aprender. En Windows, py es el lanzador de Python que trae el instalador de python.org; en macOS y Linux el comando suele ser python3.

El paquete se llama pyzed-ui en PyPI (el nombre pyzed ya estaba ocupado), pero se importa como pyzed. Los wheels precompilados para Linux, macOS y Windows incluyen el motor de Rust, así que no necesitas compilar nada.

Desde el código fuente

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

pip install git+https://github.com/albakore/pyzed     # con .venv activado

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

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

Esto compila la extensión de Rust, así que necesitas Rust 1.88 o superior (rustup update actualiza uno más antiguo) y las dependencias de sistema de tu plataforma:

# 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

Desarrollar Pyzed

Para trabajar en Pyzed, clona el repositorio. Necesitas Rust 1.88 o superior (rustup update actualiza uno más antiguo) y las dependencias del sistema de arriba.

git clone https://github.com/albakore/pyzed
cd pyzed
uv sync                          # crea .venv, compila el núcleo de Rust (release) e instala 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        # repítelo después de cambiar código de Rust
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        # repítelo después de cambiar código de Rust
pytest tests
python examples/gallery.py

uv sync también instala el grupo test (maturin y pytest). La primera compilación tarda unos minutos.
Los cambios en Python (python/pyzed/) se usan directamente.
Con uv, el siguiente uv run o uv sync después de cambiar código de Rust (src/) recompila el núcleo solo; con pip, vuelve a ejecutar maturin develop --release. Usa --release: la build de depuración es mucho más lenta al usar la ventana.
uv sync --extra designer añade ty y ruff para el editor de código del diseñador.
En Linux, una build desde el código no suena por defecto, así que compila sin paquetes extra del sistema: pyzed.audio renderiza offline y con su reloj silencioso. Para dispositivos de audio y MIDI, instala las cabeceras de ALSA (sudo apt install libasound2-dev pkg-config; Fedora: sudo dnf install alsa-lib-devel) y compila con maturin develop --release --features alsa (con uv, deja exportado MATURIN_PEP517_ARGS="--features alsa" y ejecuta uv sync --reinstall-package pyzed-ui).

Linux y WSL

Pyzed ajusta algunas cosas antes de abrir la primera ventana:

Silencia los avisos del driver de la GPU. Mesa imprime mensajes como libEGL warning: failed to get driver name for fd -1 o MESA: error: ZINK: failed to choose pdev mientras el renderer busca un backend que funcione. No afectan a nada, así que Pyzed define EGL_LOG_LEVEL=fatal y MESA_LOG=null. Con PYZED_GPU_LOGS=1 vuelven a aparecer.
En WSL usa X11. El compositor Wayland de WSLg corta la conexión al maximizar o redimensionar una ventana, y eso imprime Io error: Broken pipe (os error 32). En WSL, Pyzed usa X11 (a través de XWayland). Con PYZED_WAYLAND=1 se mantiene Wayland.
En WSL abre las páginas en el navegador de Windows. WSL no suele tener navegador propio, así que los inicios de sesión (los de los agentes de IA), la documentación y los demás enlaces se abren en tu navegador predeterminado de Windows. Las páginas que vuelven a Pyzed en 127.0.0.1 siguen llegando gracias al reenvío de localhost de WSL. Los programas que necesitan una terminal, como el inicio de sesión de Claude Code, se abren en Windows Terminal (o en una consola) dentro de tu distribución de WSL. Con BROWSER eliges el navegador tú.

Las variables que definas tú (EGL_LOG_LEVEL, MESA_LOG, WAYLAND_DISPLAY, BROWSER…) nunca se tocan.

WSL: ventanas nativas de Windows

En WSL, Pyzed abre cada ventana como un programa nativo de Windows, no a través de WSLg: pyzed design, pyzed run, pyzed dev, tus scripts que llaman a pz.run, Ejecutar en Pyzed Design y las vistas en vivo de los agentes de IA. La ventana es una ventana de Windows de verdad, dibujada con los drivers de GPU de Windows, así que va más rápida y se acopla, escala y aparece en la barra de tareas como cualquier otra aplicación. Tu código y tu proyecto siguen en WSL: sigues editando en Linux (en Zed, por ejemplo) y la recarga en caliente recoge cada guardado.

Solo necesita uv en Windows. Pyzed puede instalarlo por ti, desde WSL:

uv run pyzed windows setup     # instala uv en Windows si falta y prepara el proyecto
uv run pyzed windows           # muestra qué se usa y dónde

Cómo funciona:

Windows lee el proyecto a través de \\wsl.localhost\<distribución>\... y arranca en la misma carpeta.
Windows tiene su propio entorno, en %LOCALAPPDATA%\pyzed\wsl\, con la misma versión de Python, las dependencias del proyecto en las versiones de uv.lock, lo que necesita el editor (agentes de IA, MCP, servidores de lenguaje) y la wheel de pyzed-ui de la misma versión (siempre una wheel ya compilada: en Windows no se compila nada). El .venv del proyecto sigue siendo el de Linux. Se crea la primera vez (unos segundos) y de nuevo solo cuando cambian las dependencias.
El comando en WSL espera a la ventana: su salida, la consola de Pyzed Design y el código de salida son los de la aplicación, y al detenerlo (Detener, Ctrl+C) la ventana se cierra.

Sin uv (ni el lanzador py de Python) en Windows, las ventanas se abren por WSLg como antes, con un aviso que explica cómo prepararlo. Para usar siempre WSLg, define PYZED_WINDOWS=0 o añade --wslg a pyzed design, run o dev.

Variable	Qué hace
`PYZED_WINDOWS=0`	Abre las ventanas por WSLg.
`PYZED_WINDOWS_ENV=NOMBRE,NOMBRE`	Más variables para la aplicación en Windows (claves de API…). Las `PYZED_*` siempre pasan.
`PYZED_WINDOWS_WHEEL`	Ruta o URL de la wheel de `pyzed-ui` para Windows (ver abajo).
`PYZED_WINDOWS_TARGET`	Target de Rust para el núcleo de un checkout (`x86_64-pc-windows-gnu` o `-msvc`).

Desde un checkout de Pyzed (uv sync en el repositorio), Windows ejecuta tu checkout: sus archivos Python se importan desde WSL, así que cada cambio se nota, y su núcleo en Rust se compila para Windows dentro de WSL (compilación cruzada), una vez por cada cambio en las fuentes de Rust (la primera compilación tarda unos minutos; en Windows no se compila nada). Necesita un compilador cruzado, que se instala una vez:

sudo apt install mingw-w64     # o clang y lld, para el target MSVC de las wheels publicadas

Sin él, las ventanas se abren por WSLg con un aviso que lo explica. PYZED_WINDOWS_WHEEL (la ruta o URL de una wheel de Windows) evita la compilación, y PYZED_WINDOWS_TARGET elige el target de Rust.

Cuando Pyzed Design corre así en Windows, todo lo que inicia corre también en Windows: Ejecutar, el script del proyecto, las vistas previas y el audio usan los dispositivos de Windows. Crear o clonar un proyecto en una carpeta de WSL usa el uv y el git de Linux, así que el proyecto y su .venv siguen siendo de Linux.

Comprobar la instalación

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

La primera línea muestra la versión; la segunda, los nombres de iconos que contienen “folder”.