I am Lino
20 de abril de 2026

Instalar Python "bien" con pyenv (y dejar de pelearte con las versiones)

Publicado el 20 de abril de 2026  •  11 minutos  • 2141 palabras
Table of contents

Si hay algo que une a la comunidad Python por encima de cualquier PEP, es el dolor compartido de tener varias versiones del intérprete conviviendo a la vez en la misma máquina.

Un día instalas Python 3.8 “para un proyecto”, al mes siguiente 3.11 porque lo exige otro, luego un instalador cualquiera te cuela Python 3.10 en el PATH sin pedir permiso… y terminas frente a la escena del crimen:

python --version     # 3.11.4
python3 --version    # 3.10.12
pip --version        # usa 3.8 en algún sitio del disco

Lanzas un pip install convencido de que apunta a tu proyecto, pero en realidad aterriza en el Python del sistema; otro proyecto deja de funcionar, VS Code se hace un lío, tú también, y de repente “odio Python” cuando lo que en realidad odias es el caos que tú mismo has ido alimentando.

Vamos a poner orden con tres ideas:

  1. Por qué las versiones múltiples de Python son un lío si las gestionas “a pelo”.
  2. Qué son los entornos virtuales (y por qué no deberías vivir sin ellos).
  3. Cómo usar pyenv para instalar, elegir y aislar versiones de Python en Windows, macOS y Linux sin frustarse.

El problema de tener mil Pythons sueltos

Python tiene dos “capas” que se mezclan con facilidad:

Si instalas Python desde la web oficial en Windows, desde el store, luego desde un IDE, luego el que trae el sistema (en Linux o macOS)… terminas con varios intérpretes repartidos por el disco. Cada uno puede tener su propia carpeta de paquetes “globales”.

Sin una herramienta que ponga orden, pasan cosas como estas:

Ahí es donde entran dos salvavidas: entornos virtuales y un gestor de versiones.

Vamos primero con lo primero.

Entornos virtuales: cada proyecto con su mini-mundo

Un entorno virtual (venv) es una carpeta que contiene:

Dentro del venv, cuando haces pip install, solo se ensucia ese entorno, no el Python global, ni el de otros proyectos.

El flujo habitual (sin pyenv todavía):

python -m venv .venv      # crear entorno virtual en la carpeta .venv
source .venv/bin/activate # Linux / macOS
# o .venv\Scripts\activate en Windows (cmd/PowerShell)

pip install requests
python main.py
deactivate                 # salir del entorno

La idea es que, por ejemplo:

Con eso ya reduces muchos dolores de cabeza.

Pero sigue faltando algo: ¿de dónde sale ese “python” que usas para crear venvs? ¿Cómo decides que este proyecto vaya con 3.8 y aquel con 3.12?

Ahí es donde brilla pyenv.

pyenv: un sheriff para tus versiones de Python

pyenv es un gestor de versiones de Python que se encarga de instalar, listar y elegir qué versión de Python se usa en cada contexto (global, por proyecto, por terminal).

Lo que hace, de forma muy resumida es:

Con eso puedes decir cosas como “en general, usa Python 3.12, pero en esta carpeta concreta, cada vez que entre, quiero 3.10”, y pyenv se encarga de redirigir los binarios a la versión correcta.

Vamos a ver cómo instalarlo y usarlo en cada sistema.

Instalar pyenv en Linux (Ubuntu como ejemplo)

En Ubuntu (y la mayoría de Linux), el método recomendado hoy es usar el script oficial pyenv-installer o pyenv.run, que prepara todo.

  1. Instala dependencias para poder compilar Python (necesario para que pyenv construya las versiones):
sudo apt-get update
sudo apt-get install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
  libffi-dev liblzma-dev

(Hay varias guías – ItsFOSS, DedicatedCore, OneUptime – que listan variantes de este conjunto; la idea es la misma: librerías de compilación y compresión.)

  1. Instala pyenv con el instalador oficial:
curl https://pyenv.run | bash

Esto suele instalar:

  1. Añade pyenv a la configuración de tu shell (ejemplo para bash):

En ~/.bashrc o ~/.bash_profile (según uses login shell o no), añade:

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
# Opcional: para pyenv-virtualenv
# eval "$(pyenv virtualenv-init -)"

Guarda y recarga:

source ~/.bashrc
  1. Comprueba:
pyenv --version

Si responde con un número en vez de un “command not found”, estás listo.

Instalar pyenv en macOS (con Homebrew)

En macOS, la vía cómoda es Homebrew .

  1. Asegúrate de tener Homebrew (brew --version). Si no, lo instalas desde brew.sh (un solo comando en la web oficial).
  2. Instala pyenv:
brew update
brew install pyenv
  1. Configura tu shell. En macOS moderno, por defecto usas zsh, así que en ~/.zshrc añade algo como:
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

(Si usas bash, lo mismo pero en ~/.bash_profile o ~/.bashrc.)

  1. Recarga el shell:
source ~/.zshrc
  1. Comprueba:
pyenv --version

Si responde bien, ya puedes empezar a instalar Pythons como si esto fuera una barra libre.

Instalar pyenv en Windows

En Windows no puedes usar el pyenv “clásico” (está pensado para Unix), pero existe pyenv-win , un port específico.

Hay dos caminos habituales: manual y con un gestor de paquetes.

Con instalador / manual (pyenv-win)

La documentación oficial de pyenv-win explica cómo clonar el repo en %USERPROFILE%\.pyenv\pyenv-win y añadir su bin y shims al PATH. Es algo más artesanal: clonar el repo con git, ajustar las variables de entorno y reiniciar la consola.

Con Chocolatey (mucho más cómodo)

Si ya usas Chocolatey (el gestor de paquetes para Windows, al estilo de apt pero en PowerShell), puedes instalar pyenv-win con un solo comando:

  1. Abre PowerShell como administrador.
  2. Ejecuta:
choco install pyenv-win
  1. Asegúrate de que las variables de entorno de pyenv-win están configuradas. La guía habitual añade:
[System.Environment]::SetEnvironmentVariable('PYENV', "$env:USERPROFILE\.pyenv\pyenv-win\", "User")
[System.Environment]::SetEnvironmentVariable('PYENV_HOME', "$env:USERPROFILE\.pyenv\pyenv-win\", "User")
[System.Environment]::SetEnvironmentVariable('PATH', "$HOME\.pyenv\pyenv-win\bin;$HOME\.pyenv\pyenv-win\shims;" + $env:Path, "User")

Cierra y abre de nuevo la terminal, y prueba:

pyenv --version

Si ves versión, ya puedes usar pyenv-win para instalar y cambiar de Python con comandos muy parecidos a los de Linux/macOS.

Usar pyenv: listar, instalar y activar versiones (global, local, shell)

Con pyenv operativo, el flujo básico es casi igual en todos los sistemas (salvo matices Windows).

Ver qué versiones hay disponibles (en remoto)

Para ver todas las versiones de Python que pyenv puede instalar:

pyenv install --list

La lista es larga: verás cosas como 3.8.18, 3.9.18, 3.10.14, 3.11.9, 3.12.3, además de versiones antiguas y hasta 2.x para arqueología.

Instalar una versión concreta

Por ejemplo, para instalar Python 3.12.1:

pyenv install 3.12.1

pyenv descargará, compilará y dejará esa versión en ~/.pyenv/versions/3.12.1 (o donde toque en Windows).

Puedes comprobar qué versiones tienes ya instaladas con:

pyenv versions

Verás algo así:

  system
  3.10.14
* 3.12.1 (set by /home/tuusuario/.python-version)

Elegir versión global, local y por shell

Aquí viene la parte interesante:

El fichero .python-version es clave: Es un archivo de texto plano que vive en la raíz de tu proyecto y dice “aquí, usa esta versión de Python”. Pyenv lo lee, ajusta sus shims, y de repente python, python3 y pip apuntan a la versión correcta sin que tengas que hacer nada más.

Puedes abrirlo y cambiarlo a mano si quieres (ej. 3.11.9 -> 3.12.1), pero lo normal es usar pyenv local.

Comprobar que realmente estás usando la versión que crees

Siempre que toques algo de pyenv, acostúmbrate a verificar:

python --version
which python     # o 'where python' en Windows

En Linux/macOS, si todo va bien, which python debería apuntar a algo tipo:

/home/tu-usuario/.pyenv/shims/python

Y esa ruta de “shim” internamente redirige a la versión que hayas elegido (global o local).

pyenv + entornos virtuales: el combo limpio

Con pyenv puedes además crear entornos virtuales asociados a versiones concretas con pyenv virtualenv (extensión que suele venir con el instalador pyenv.run). El flujo típico:

# Proyecto nuevo
mkdir ~/proyectos/webapp && cd ~/proyectos/webapp

# Instalar Python deseado (si no lo tienes ya)
pyenv install 3.12.1

# Crear un virtualenv llamado webapp-env con esa versión
pyenv virtualenv 3.12.1 webapp-env

# Hacer que en esta carpeta se use ese entorno
pyenv local webapp-env

# Verificar
python --version
which python

A partir de ahí:

pip install flask requests pytest

y todas esas dependencias vivirán solo dentro de webapp-env. Otro proyecto puede usar 3.10.14 y tener su propio virtualenv sin interferir.

El resultado es exactamente lo que buscábamos:

Conclusión: un entorno limpio cuida de ti (y del planeta, un poco)

Puede sonar exagerado, pero un entorno de Python ordenado ahorra tiempo, frustración y recursos. Menos horas persiguiendo bugs causados por versiones cruzadas, menos reinstalaciones salvajes, menos contenedores enormes porque “yo qué sé qué hay instalado en mi máquina”.

Con pyenv decides qué Python va con qué proyecto, y con entornos virtuales decides qué paquetes viven dónde. El sistema se ensucia menos, tu cabeza también, y hasta tus builds de CI pueden ir más ligeras al saber exactamente qué necesitan.

Si nos ponemos poéticos: cada proyecto con su versión clara de Python y sus dependencias justas es un pequeño acto de sostenibilidad digital. Menos basura instalada “por si acaso”, menos tiempo de CPU rehaciendo lo que ya deberíamos tener controlado… y más energía (tuya y de la máquina) dedicada a hacer cosas que importan.

Y si no quieres pensar en el planeta, piensa en ti dentro de seis meses abriendo un repo viejo y diciendo:

“Gracias, yo del pasado, por haber dejado aquí un .python-version y un entorno limpio. Me has salvado la tarde.”

Glosario rápido

No te preocupes, nadie nació sabiendo qué es un shim. Para eso está esto.

Fuentes y referencias

Si alguien te pregunta de dónde has sacado todo esto, aquí tienes las pruebas.

Sígueme

Escribo y opino sobre tecnología, desarrollo de software y lo que se me pase por la cabeza.