# Instalación

> Instala Pyzed con pip o uv en Windows, macOS y Linux. Los wheels precompilados incluyen el motor en Rust: solo necesitas Python 3.10 o superior.

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

Pyzed necesita **Python 3.10 o superior**.

## Desde PyPI

- **uv** gestiona el proyecto por ti: [Crear un proyecto](https://albakore.github.io/pyzed/es/getting-started/new-project/) empieza una app
  nueva así, y es lo que usa el resto de esta documentación. Instálalo desde
  [docs.astral.sh/uv](https://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](https://www.python.org/downloads/); 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.

**Solo wheels precompilados:**

En PyPI solo hay wheels, compilados y probados por el pipeline de releases para Linux (x86_64 y ARM, glibc y
musl), macOS (Intel y Apple Silicon) y Windows (x64 y ARM). Un mismo wheel sirve para cualquier Python desde
3.10. En otra plataforma la instalación se detiene con un error en lugar de compilar; ahí instala desde el
código fuente (abajo).

## Desde el código fuente

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

**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:**

Instala [Rust con rustup](https://rustup.rs) y las *Build Tools for Visual Studio*
(carga de trabajo "Desarrollo para el escritorio con C++").

## Desarrollar Pyzed

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

- `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](https://docs.astral.sh/uv/getting-started/installation/). Pyzed puede instalarlo por
ti, desde WSL:

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

:::note[Si trabajas en Pyzed]
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:

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

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