Cómo instalar y configurar Python en Ubuntu con pyenv

Segundo lenguaje de la serie: Python. En este artículo vas a aprender exactamente cómo instalarlo en Ubuntu o WSL con pyenv, gestionando varias versiones a la vez y con entornos virtuales integrados gracias a pyenv-virtualenv.

Python tiene una trampa particular en Ubuntu: el sistema ya trae uno, y tocarlo es mala idea porque el propio sistema operativo depende de él. He visto entornos rotos por “actualizar el Python del sistema”: herramientas del sistema que dejan de funcionar y proyectos que compilan contra la versión equivocada.

El problema es que la mayoría trabaja directo con ese Python del sistema, instala paquetes con sudo pip y cruza los dedos. Funciona hasta que dos proyectos piden versiones distintas, o hasta que un apt upgrade cambia las reglas del juego.

Vamos a ver:

1. Instalar las dependencias de compilación.
2. Instalar pyenv con su instalador oficial (incluye pyenv-virtualenv).
3. Configurar tu shell correctamente.
4. Instalar versiones de Python, elegir la global y fijarla por proyecto.
5. Crear entornos virtuales ligados a pyenv.

Al final tendrás Python gestionado por completo desde tu usuario, sin tocar jamás el del sistema.

Tabla de contenidos

Paso 1: Instala las dependencias de compilación

A diferencia de Node.js, pyenv compila Python desde el código fuente, así que las dependencias importan de verdad. Si seguiste el setup profesional de la serie ya tienes la mayoría; este bloque garantiza las que Python necesita:

sudo apt update && sudo apt install -y \
  build-essential curl git libssl-dev zlib1g-dev libbz2-dev \
  libreadline-dev libsqlite3-dev libncurses-dev xz-utils tk-dev \
  libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev ca-certificates

Paso 2: Instala pyenv

El instalador oficial hace todo en un comando:

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

Esto instala pyenv y sus plugins oficiales, incluido pyenv-virtualenv (los entornos virtuales que usaremos al final) y pyenv-update (para actualizarlo después).

Paso 3: Configura tu shell

Si usas zsh (el que configuramos con Oh My Zsh), reparte la configuración: variables y PATH en ~/.zprofile, inicialización interactiva en ~/.zshrc.

echo '' >> ~/.zprofile
echo '# Configuración base de pyenv' >> ~/.zprofile
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile

echo '' >> ~/.zshrc
echo '# Inicialización interactiva de pyenv' >> ~/.zshrc
echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc

Si usas bash, todo va junto en ~/.bashrc, cambiando zsh por bash en la línea de init.

Recarga y verifica:

exec "$SHELL"
pyenv --version

Paso 4: Instala Python y define la versión global

Consulta las versiones estables recientes:

pyenv install -l | grep -E '^[[:space:]]*[0-9]+\.[0-9]+\.[0-9]+$' | tail -n 20

Instala la que necesites (usa la más reciente de la lista) y déjala como predeterminada:

pyenv install 3.13.5
pyenv global 3.13.5

Verifica:

python --version
pip --version
pyenv version

Fíjate en el detalle: python a secas (no python3) ya apunta a tu versión, no a la del sistema.

Paso 5: Fija la versión por proyecto

Dentro de la carpeta de un proyecto:

cd mi-proyecto
pyenv local 3.13.5

Esto crea un archivo .python-version: al entrar a esa carpeta, pyenv activa esa versión automáticamente. Quien clone el repo trabaja con la misma versión que tú.

Paso 6: Crea entornos virtuales con pyenv-virtualenv

La gran recompensa de esta configuración. En Python, cada proyecto debería tener su propio entorno aislado de paquetes, y pyenv-virtualenv los integra al flujo que ya conoces:

pyenv virtualenv 3.13.5 mi-proyecto-313
pyenv local mi-proyecto-313

Con eso, el .python-version del proyecto apunta al entorno virtual completo: entras a la carpeta y tienes la versión correcta de Python y sus paquetes aislados, sin activate manual.

Verifica en cualquier momento:

pyenv versions
pyenv which python

Solución de problemas comunes

pyenv: command not found

La configuración del shell no quedó aplicada. Revisa que las líneas estén en los archivos correctos y reinicia la terminal.

Falla la compilación de una versión

Es una dependencia faltante en el 99% de los casos: vuelve a ejecutar el bloque del Paso 1 y reintenta.

python sigue apuntando al del sistema

which python
pyenv version

Si la ruta no sale de ~/.pyenv, falta la inicialización del Paso 3 en tu shell.

Mantenimiento

Actualizar pyenv y sus plugins (gracias a pyenv-update, instalado en el Paso 2):

pyenv update

Y para eliminar una versión o entorno que ya no uses:

pyenv uninstall 3.13.5

Conclusión

Python del sistema intacto, tus versiones compiladas en tu usuario, .python-version por proyecto y entornos virtuales integrados: esa es la diferencia entre pelear con Python y trabajar con él.

Si esto te fue útil, el artículo relacionado es el paso lógico: Setup Ubuntu y WSL para desarrollo profesional, la base de dependencias que hace que pyenv compile sin sorpresas.

El sábado publico esta misma configuración para macOS. Si no te lo quieres perder, suscríbete al newsletter en la portada del blog.

Recursos adicionales

• Cómo instalar y configurar Node.js en Ubuntu con nodenv
• Documentación oficial de pyenv
• pyenv-virtualenv