¿Qué es pyenv y cómo instalarlo?

¿Qué es pyenv?

Respuesta corta: pyenv es una herramienta que instala varias versiones de Python en el mismo ordenador y te deja cambiar de una a otra con un comando. Cada proyecto puede usar su propia versión, y el Python que trae tu sistema no se toca.

pyenv install 3.15.2        # instala una versión
pyenv global 3.15.2         # la de por defecto para tu usuario
cd app-antigua && pyenv local 3.14.10   # esta carpeta usa 3.14
python --version            # Python 3.14.10

pyenv funciona en macOS y Linux. En Windows se usa pyenv-win, un proyecto aparte con los mismos comandos. Al escribir esta guía, las últimas versiones son pyenv 2.8.14, pyenv-win 3.1.1 y Python 3.15.2.

pyenv install descarga una versión, pyenv global la convierte en tu versión por defecto y pyenv local fija otra distinta para un solo proyecto.

Los comandos de pyenv de un vistazo

¿Para qué se usa pyenv?

• Proyectos distintos, versiones distintas. Una app antigua puede necesitar Python 3.12 y una nueva usar 3.15. pyenv cambia solo al entrar en cada carpeta.
• Probar una versión nueva sin riesgo. Instala el último Python junto al que usas, prueba tu código y vuelve atrás con un comando.
• Sin sudo y sin cambios en el sistema. Cada versión vive en ~/.pyenv/versions, dentro de tu carpeta de usuario. Las herramientas de macOS y Linux que dependen del Python del sistema siguen funcionando.
• La misma versión para todo el equipo. Sube el archivo .python-version al repositorio y todos los que usen pyenv tendrán el mismo Python en ese proyecto.

pyenv elige la versión en este orden: la variable PYENV_VERSION (la fija pyenv shell), un archivo .python-version en la carpeta actual o en una carpeta superior (lo crea pyenv local) y, por último, la versión global.

Instalar pyenv en Mac

1. Instala las herramientas de compilación y las librerías. pyenv compila Python desde el código fuente, así que las necesita antes:

xcode-select --install
brew install openssl readline sqlite3 xz tcl-tk@8 libb2 zstd zlib pkgconfig

2. Instala pyenv con Homebrew:

brew update
brew install pyenv

3. Añade pyenv a zsh, la shell por defecto de macOS:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc

4. Reinicia la shell y compruébalo:

exec "$SHELL"
pyenv --version   # pyenv 2.8.14

Funciona igual en Mac con Apple Silicon y con Intel.

Instalar pyenv en Linux

1. Instala las dependencias de compilación. En Ubuntu, Debian o Mint:

sudo apt update; sudo apt install make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl git \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev libzstd-dev

2. Ejecuta el instalador oficial. Clona pyenv en ~/.pyenv y añade el comando pyenv update:

curl -fsSL https://pyenv.run | bash

Si lo prefieres, clónalo tú con git clone https://github.com/pyenv/pyenv.git ~/.pyenv.

3. Añade pyenv a bash:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init - bash)"' >> ~/.bashrc

Si tienes ~/.profile o ~/.bash_profile, añade también ahí las mismas tres líneas, cambiando el nombre del archivo. Con zsh, usa ~/.zshrc y pyenv init - zsh, como en Mac.

4. Reinicia la shell: exec "$SHELL" y compruébalo con pyenv --version.

Instalar pyenv en Windows con pyenv-win

pyenv no funciona en Windows. Instala pyenv-win desde PowerShell:

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"

Cierra y vuelve a abrir PowerShell y ejecuta pyenv --version. Los comandos son los mismos que en Mac y Linux: pyenv install, pyenv global y pyenv local. Ejecuta antes pyenv update para que pyenv-win conozca las versiones de Python más nuevas.

Si trabajas en WSL (Ubuntu dentro de Windows), sigue los pasos de Linux dentro de WSL. Tienes todos los detalles en la guía para instalar pyenv en Windows.

Instalar y cambiar de versión de Python

pyenv install --list | grep " 3.15"   # versiones que puedes instalar
pyenv install 3.15.2
pyenv install 3.14.10
pyenv versions
#   system
#   3.14.10
# * 3.15.2 (set by /home/ana/.pyenv/version)

Fija la versión por defecto de tu usuario y otra distinta para un proyecto:

pyenv global 3.15.2
 
cd app-antigua
pyenv local 3.14.10        # crea app-antigua/.python-version
python --version           # Python 3.14.10

Al salir de la carpeta vuelve la versión global. Para volver al Python que trae tu sistema, ejecuta pyenv global system.

pyenv o venv: usa los dos

Resuelven problemas distintos:

Lo habitual es pyenv para elegir la versión y venv para los paquetes:

cd mi-app
pyenv local 3.15.2
python -m venv .venv
source .venv/bin/activate
pip install requests

El plugin pyenv-virtualenv puede crear entornos con pyenv virtualenv 3.15.2 mi-app, pero venv basta para la mayoría de los proyectos.

Actualizar pyenv

• Instalado con Homebrew: brew update && brew upgrade pyenv
• Instalado con pyenv.run: pyenv update
• Instalado con git: git -C ~/.pyenv pull
• pyenv-win: vuelve a ejecutar el instalador de PowerShell, o pyenv update para refrescar la lista de versiones

Actualiza pyenv cuando pyenv install --list no muestre una versión de Python que acaba de salir.

Usa la IA para configurar pyenv

Un asistente como ChatGPT, Claude o GitHub Copilot puede adaptar la instalación a tu sistema y leer contigo un error. Estos tres prompts están listos para copiar.

1. Configura pyenv para tu sistema

Uso [macOS con Apple Silicon / Ubuntu 24.04 / Windows 11] con [zsh / bash / PowerShell].
Dame los pasos exactos para instalar pyenv, configurarlo en mi shell
e instalar Python [versión]. Explica qué hace cada paso.

2. Arregla una instalación que falló

pyenv install [versión] falló en [tu sistema] con esta salida:
[pega las últimas 30 líneas]
Explica qué dependencia falta y dame el comando para arreglarlo.

3. Prepara un proyecto

Mi proyecto necesita Python [versión] y estos paquetes: [lista].
Muéstrame cómo prepararlo con pyenv local y venv para que todo mi equipo tenga lo mismo.

Lee cada comando antes de ejecutarlo, sobre todo los que usan sudo o cambian los archivos de tu shell.

Problemas comunes con pyenv

Guías relacionadas

• Cómo instalar Python
• Cómo actualizar Python en la terminal
• Cómo instalar pyenv en Windows
• Cómo leer un archivo en Python
• Cómo consumir una API en Python
• Cómo concatenar cadenas en Python