Guía de instalación de uv: cómo elegir entre macOS, Linux, Windows, pipx, Homebrew y WinGet

Thu, 07 May 2026 23:23:58 +0800

uv es un gestor de toolchain de Python creado por Astral. Sirve para gestionar versiones de Python, entornos virtuales, dependencias, scripts, proyectos y herramientas. Tiene muchas formas de instalación. La documentación oficial ofrece instaladores independientes y también admite PyPI, Homebrew, WinGet, Scoop, Docker, GitHub Releases y Cargo.

Si solo quieres instalarlo rápido, da prioridad al instalador independiente oficial. Si prefieres mantener la versión mediante el gestor de paquetes del sistema, usa Homebrew, WinGet o Scoop. Si ya acostumbras instalar herramientas de Python en entornos aislados, puedes usar pipx.

Elección rápida

Escenario	Método recomendado	Comando
Instalación rápida en macOS / Linux	Instalador independiente oficial	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
macOS / Linux sin curl	Script oficial + wget	`wget -qO- https://astral.sh/uv/install.sh \| sh`
Instalación rápida en Windows	Instalador de PowerShell	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`
Instalación aislada de herramientas Python	pipx	`pipx install uv`
Instalación temporal o tradicional de Python	pip	`pip install uv`
Gestión de paquetes en macOS	Homebrew	`brew install uv`
Usuarios de MacPorts en macOS	MacPorts	`sudo port install uv`
Gestión de paquetes en Windows	WinGet	`winget install --id=astral-sh.uv -e`
Usuarios de Scoop en Windows	Scoop	`scoop install main/uv`
Usuarios de Rust	Cargo	`cargo install --locked uv`

Las opciones generales más recomendables son:

macOS / Linux: instalador independiente oficial;
Windows: instalador oficial de PowerShell o WinGet;
si ya gestionas herramientas CLI de Python con pipx: pipx install uv.

macOS y Linux: instalador oficial

El método oficial más directo consiste en descargar el script con curl y ejecutarlo con sh:

`1`	`curl -LsSf https://astral.sh/uv/install.sh \| sh`

Si el sistema no tiene curl, puedes usar wget:

`1`	`wget -qO- https://astral.sh/uv/install.sh \| sh`

Si quieres instalar una versión concreta, coloca el número de versión en la URL. Por ejemplo, el ejemplo oficial usa 0.11.11:

`1`	`curl -LsSf https://astral.sh/uv/0.11.11/install.sh \| sh`

Este método encaja con la mayoría de entornos personales de desarrollo. Es simple, multiplataforma y funciona mejor con el mecanismo oficial de actualización de uv.

El instalador coloca binarios como uv y uvx bajo el directorio del usuario, y puede modificar el shell profile para que los comandos puedan usarse directamente desde la terminal. Si no quieres que el instalador modifique PATH, revisa las opciones oficiales del installer, por ejemplo configurando UV_NO_MODIFY_PATH=1.

Windows: instalador de PowerShell

El método oficial en Windows es ejecutar el script de instalación con PowerShell:

`1`	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`

Para instalar una versión concreta, también puedes poner el número de versión en la URL:

`1`	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.11.11/install.ps1 \| iex"`

Aquí ExecutionPolicy ByPass permite obtener y ejecutar el script de instalación desde internet. Como hábito de seguridad, puedes revisar el contenido del script antes de ejecutarlo:

`1`	`powershell -c "irm https://astral.sh/uv/install.ps1 \| more"`

Si estás acostumbrado a gestores de paquetes de Windows, también puedes priorizar WinGet o Scoop.

Instalar con pipx

La documentación oficial indica que uv se publica en PyPI. Si lo instalas desde PyPI, se recomienda ponerlo en un entorno aislado, por ejemplo con pipx:

`1`	`pipx install uv`

Este método es adecuado si ya usas pipx como gestor de herramientas CLI de Python. Evita mezclar uv con el entorno del proyecto actual.

Si no tienes pipx, también puedes usar pip directamente:

`1`	`pip install uv`

Pero ten en cuenta que uv ofrece wheels precompilados en muchas plataformas. Si una plataforma no tiene un wheel compatible, se construirá desde código fuente, y en ese caso necesitarás una toolchain de Rust.

Mi recomendación: en una máquina personal, pipx install uv es más limpio que pip install uv; dentro de un entorno de proyecto, no recomiendo instalar uv como dependencia del proyecto.

Homebrew, MacPorts, WinGet y Scoop

Si prefieres gestores de paquetes del sistema, uv también admite canales comunes.

En macOS, usa Homebrew:

`1`	`brew install uv`

Los usuarios de MacPorts pueden usar:

`1`	`sudo port install uv`

En Windows, usa WinGet:

`1`	`winget install --id=astral-sh.uv -e`

Los usuarios de Scoop pueden usar:

`1`	`scoop install main/uv`

La ventaja de estos métodos es que delegan el mantenimiento en el gestor de paquetes del sistema. La desventaja es que el ritmo de actualización depende del origen de paquetes correspondiente, no del instalador oficial de uv.

Docker, GitHub Releases y Cargo

uv también ofrece imágenes Docker en GitHub Container Registry:

`1`	`ghcr.io/astral-sh/uv`

Esto sirve para CI, Dockerfiles, creación de imágenes y entornos temporales de ejecución. En uso real, conviene revisar también la documentación oficial de integración con Docker.

Si quieres descargar binarios manualmente, puedes hacerlo desde GitHub Releases. Cada página de release suele incluir binarios para las plataformas compatibles y explicar cómo llamar al instalador independiente usando una URL de GitHub.

Los usuarios de Rust también pueden instalar desde crates.io:

`1`	`cargo install --locked uv`

Pero este método compila desde código fuente y requiere una toolchain de Rust compatible. A menos que necesites instalarlo explícitamente desde el ecosistema Rust, los usuarios normales no tienen por qué elegir Cargo primero.

Actualizar uv

Si uv se instaló mediante el instalador independiente oficial, puedes usar el comando de autoactualización:

`1`	`uv self update`

La documentación oficial indica que actualizar uv vuelve a ejecutar el instalador y puede modificar el shell profile. Si no quieres que la actualización modifique PATH, configura:

`1`	`UV_NO_MODIFY_PATH=1`

Si lo instalaste de otra forma, debes actualizarlo con el gestor correspondiente. Por ejemplo, si lo instalaste con pip, usa:

`1`	`pip install --upgrade uv`

Homebrew, WinGet, Scoop y MacPorts también deben usar sus propios comandos de actualización.

Activar autocompletado de shell

uv admite autocompletado de shell. La documentación oficial recomienda comprobar primero cuál es tu shell actual:

`1`	`echo $SHELL`

Bash:

`1`	`echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc`

Zsh:

`1`	`echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc`

fish:

`1`	`echo 'uv generate-shell-completion fish \| source' > ~/.config/fish/completions/uv.fish`

PowerShell:

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

Si también usas uvx con frecuencia, puedes activar el autocompletado de uvx por separado.

Bash:

`1`	`echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc`

Zsh:

`1`	`echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc`

fish:

`1`	`echo 'uvx --generate-shell-completion fish \| source' > ~/.config/fish/completions/uvx.fish`

PowerShell:

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uvx --generate-shell-completion powershell) | Out-String | Invoke-Expression'

Después de configurarlo, reinicia el shell o recarga el archivo de configuración correspondiente.

Desinstalar uv

Para desinstalar uv, primero puedes limpiar la caché y los datos gestionados por uv:

1
2
3

uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

Después elimina los binarios.

macOS / Linux:

`1`	`rm ~/.local/bin/uv ~/.local/bin/uvx`

Windows:

1
2
3

rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe
rm $HOME\.local\bin\uvw.exe

La documentación oficial también recuerda que antes de 0.5.0, uv se instalaba en ~/.cargo/bin. Si actualizaste desde una versión antigua, es posible que los binarios viejos sigan allí y debas eliminarlos manualmente.

Qué hacer después de instalar

Después de instalar, conviene confirmar primero la versión:

`1`	`uv --version`

Luego puedes empezar con algunas tareas comunes:

uv python install
uv venv
uv pip install requests
uvx ruff --version

Si es un proyecto nuevo, puedes seguir aprendiendo:

uv init: inicializar un proyecto;
uv add: añadir dependencias;
uv sync: sincronizar el entorno;
uv run: ejecutar comandos dentro del entorno del proyecto;
uvx: ejecutar temporalmente herramientas CLI de Python.

Mi recomendación

En una máquina personal de desarrollo, prioriza el instalador independiente oficial, porque es el método más alineado con la documentación oficial de uv y admite uv self update.

Si usas Windows y no quieres ejecutar un script remoto, puedes usar WinGet o Scoop. Si usas macOS y prefieres que todas tus herramientas las gestione Homebrew, puedes usar directamente brew install uv.

Quienes ya gestionan herramientas CLI de Python con pipx pueden usar pipx install uv. Pero no recomiendo ejecutar pip install uv dentro del entorno virtual de un proyecto concreto, porque eso mezcla la toolchain con las dependencias del proyecto.

Si se trata de CI o construcción de contenedores, revisa primero Docker y GitHub Releases, y fija la versión según el flujo de creación de la imagen.

Enlaces relacionados

Documentación de instalación de uv: https://docs.astral.sh/uv/getting-started/installation/
uv First steps: https://docs.astral.sh/uv/getting-started/first-steps/
Integración de uv con Docker: https://docs.astral.sh/uv/guides/integration/docker/
uv GitHub Releases: https://github.com/astral-sh/uv/releases

Uv on KnightLi Blog