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

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:

1
2
3
4

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:

1
2
3
4

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:

1
2
3
4

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