El mundo de la programación en Python

pyenv: Guía completa para instalar y gestionar versiones de Python en macOS y Linux (con virtualenv)

Gestión de paquetes y entornos
目次

1. ¿Qué es pyenv?

Para las y los desarrolladores de Python, es muy común necesitar distintas versiones de Python según cada proyecto. En esos casos resulta útil “pyenv”. pyenv es una herramienta que permite gestionar múltiples versiones de Python y cambiar fácilmente entre versiones diferentes por proyecto.

Retos de la gestión de versiones de Python

A medida que avanzas en el desarrollo con Python, puede que distintos proyectos requieran versiones diferentes. Por ejemplo, un proyecto podría usar Python 3.9 mientras otro necesita Python 2.7. Normalmente solo hay una versión instalada en el sistema, por lo que alternar versiones se vuelve engorroso. pyenv resuelve este problema.

Ventajas de pyenv

Con pyenv obtienes beneficios como:
  1. Cambio de versión sencillo: con pyenv puedes cambiar la versión de Python a nivel de sistema o por proyecto de forma simple.
  2. Gestión de múltiples versiones: administra con un solo comando varias versiones instaladas de Python en tu sistema. Así podrás adaptarte con flexibilidad a dependencias y diferencias entre proyectos.
  3. Disponible en muchos sistemas (excepto Windows): es compatible con macOS y Linux, entre otros.

Cómo funciona pyenv

pyenv crea directorios separados para cada versión de Python e instala allí cada versión. Con los comandos pyenv global y pyenv local puedes especificar qué versión usar en todo el sistema o solo en un proyecto concreto.

2. Cómo instalar pyenv

Resumen

Para usar pyenv, primero debes instalarlo en tu sistema. En esta sección se explican los pasos para macOS y Linux. En Windows, pyenv no está soportado oficialmente; se recomienda usar otros métodos (como WSL o Anaconda).

Instalación en macOS

En macOS, puedes instalar pyenv fácilmente con Homebrew, el gestor de paquetes para macOS. Sigue estos pasos:
  1. Comprobar la instalación de Homebrew Abre la terminal y ejecuta:
   brew --version
Si ves la información de versión, Homebrew ya está instalado. De lo contrario, consulta las instrucciones en el sitio oficial (Homebrew公式サイト).
  1. Instalar pyenv Si Homebrew está disponible, instala pyenv con:
   brew install pyenv
Cuando termine la instalación, continúa con el siguiente paso.
  1. Configurar variables de entorno Para usar pyenv, añade su configuración al entorno de tu shell. Normalmente se edita .bash_profile o .zshrc. Ejecuta:
   echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
   echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile
   echo 'eval "$(pyenv init --path)"' >> ~/.bash_profile
Si usas .zshrc, añade estas líneas ahí en lugar de .bash_profile. Tras ello, reinicia la terminal o aplica los cambios con:
   source ~/.bash_profile
  1. Verificar la instalación Ejecuta el siguiente comando para confirmar que pyenv quedó instalado:
   pyenv --version
Si se muestra un número de versión, pyenv está listo.

Instalación en Linux

En Linux, la instalación es similar a macOS, pero con gestores de paquetes como apt o yum. A continuación, los pasos para Ubuntu:
  1. Instalar paquetes necesarios Antes de instalar pyenv, instala las dependencias:
   sudo apt update
   sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev 
   libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev 
   xz-utils tk-dev libffi-dev liblzma-dev python-openssl git
  1. Instalar pyenv Clona el repositorio e instálalo (vía script):
   curl https://pyenv.run | bash
  1. Configurar variables de entorno Para habilitar pyenv, añade lo siguiente a .bashrc o .zshrc:
   export PATH="$HOME/.pyenv/bin:$PATH"
   eval "$(pyenv init --path)"
Reinicia la terminal o ejecuta source ~/.bashrc para aplicar los cambios.
  1. Verificar la instalación Comprueba que pyenv funciona:
   pyenv --version

Solución de problemas

Si aparecen errores al instalar pyenv, puede que falten bibliotecas de dependencias. En Linux, según la distribución, pueden variar. Consulta la documentación oficial y añade las librerías necesarias.
RUNTEQ（ランテック）｜超実戦型エンジニア育成スクール

3. Gestión de versiones de Python

Tras instalar pyenv, aprende a gestionar versiones: instalarlas y alternarlas.

Instalar versiones de Python

Con pyenv es sencillo instalar distintas versiones. Por ejemplo, si un proyecto usa Python 3.8 y otro 3.9:
  1. Comprobar la lista de versiones Muestra las versiones disponibles para instalar:
   pyenv install --list
Se listan todas las versiones soportadas por pyenv para que elijas la que necesitas.
  1. Instalar una versión concreta Para instalar una versión específica:
   pyenv install 3.9.1
Este comando instala Python 3.9.1. Si necesitas varias versiones, instálalas individualmente.

Cambiar la versión de Python

Con pyenv puedes alternar entre versiones instaladas y evitar conflictos de dependencias por proyecto.
  1. Cambiar la versión global (todo el sistema) Para definir la versión usada en todo el sistema:
   pyenv global 3.9.1
Así, Python 3.9.1 se usará en cualquier directorio.
  1. Cambiar la versión a nivel de proyecto Si solo quieres otra versión en un directorio concreto, usa pyenv local:
   pyenv local 3.8.0
Este ajuste se aplica únicamente al directorio actual; en otros rige lo definido por pyenv global.
  1. Comprobar la versión activa Para ver la versión de Python en uso (global o local):
   pyenv version

Desinstalar versiones

Si un proyecto deja de necesitar una versión o la instalaste por error, puedes eliminarla:
  1. Método de desinstalación Ejecuta:
   pyenv uninstall 3.9.1
Con ello se elimina Python 3.9.1 del sistema.

4. Uso conjunto con virtualenv

pyenv facilita la gestión de versiones. Para aislar dependencias por proyecto de forma eficiente, es habitual combinarlo con virtualenv (entornos virtuales). Aquí verás cómo usarlos juntos y por qué es útil.

¿Qué es virtualenv?

virtualenv crea entornos virtuales independientes por proyecto para aislar bibliotecas y paquetes. Así, varios proyectos en la misma máquina pueden usar versiones diferentes de paquetes sin interferir entre sí. Por ejemplo, si el proyecto A usa requests 2.0 y el B la 3.0, cada uno puede tener su propio entorno.

Diferencias entre pyenv y virtualenv

pyenv se centra en la gestión de versiones de Python (instalar y alternar versiones a nivel global o local). virtualenv gestiona las dependencias de bibliotecas/paquetes dentro de entornos aislados. Combinarlos aporta:
  • Gestionar múltiples versiones: con pyenv instalas distintas versiones y fijas la óptima por proyecto.
  • Aislar dependencias por proyecto: con virtualenv creas entornos que evitan conflictos de paquetes.

Instalar pyenv-virtualenv

Además de pyenv, el plugin pyenv-virtualenv simplifica aún más la creación y gestión de entornos.
  1. Instalación Instálalo con:
   brew install pyenv-virtualenv
En Linux, puedes usar:
   git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv
  1. Configurar variables de entorno Tras la instalación, añade estas líneas al archivo de configuración de tu shell para habilitar pyenv-virtualenv:
   echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bash_profile
   source ~/.bash_profile

Crear un entorno virtual

Con pyenv-virtualenv puedes crear entornos por versión. Por ejemplo, para Python 3.8.0:
pyenv virtualenv 3.8.0 my_project_env
Esto crea el entorno my_project_env basado en Python 3.8.0.

Cambiar de entorno

Para usar el entorno en un proyecto, ejecuta:
pyenv local my_project_env
Así, el entorno my_project_env queda activo solo en ese directorio. En otros, se usa la versión global.

Eliminar un entorno

Si ya no lo necesitas, elimínalo con:
pyenv uninstall my_project_env

Ventajas de virtualenv

Al combinar pyenv y virtualenv, separas completamente versiones de Python y dependencias por proyecto. Esto reduce el riesgo de conflictos y mantiene entornos estables.

5. Precauciones al usar pyenv

Aunque pyenv y virtualenv hacen muy eficiente la gestión de versiones y entornos, hay puntos a cuidar y focos típicos de error. Aquí verás problemas comunes y sus soluciones.

1. Soporte limitado en Windows

pyenv se recomienda principalmente en macOS y Linux. En Windows no está soportado de forma directa. Si quieres usarlo en Windows, considera:
  • Usar Windows Subsystem for Linux (WSL): instala WSL para tener un entorno Linux donde usar pyenv como si fuera Linux nativo.
  • Usar Anaconda: como alternativa a pyenv para gestionar múltiples versiones de Python y entornos en Windows.

2. Errores por falta de dependencias

En Linux, si faltan bibliotecas necesarias durante la instalación, pueden aparecer mensajes como:
WARNING: The Python bz2 extension was not compiled. Missing the bzip2 lib?
Cómo resolver:
  • Instala las dependencias necesarias (por ejemplo, libbz2-dev, libssl-dev, etc.) y vuelve a ejecutar pyenv install. Por ejemplo:
   sudo apt-get install -y build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev

3. Conflictos entre Python del sistema y pyenv

Puede haber conflictos entre el Python preinstalado del sistema y las versiones gestionadas por pyenv, normalmente por configuraciones de PATH o inicialización del shell incorrectas. Cómo resolver:
  • Verifica que tu archivo de inicio del shell (p. ej., .bashrc o .zshrc) contenga la configuración correcta de pyenv, incluyendo:
   export PATH="$HOME/.pyenv/bin:$PATH"
   eval "$(pyenv init --path)"
  • Tras ello, reinicia la terminal o ejecuta source ~/.bashrc.

4. Fallos al instalar versiones específicas

Si falla la instalación de una versión concreta, suele deberse a la ausencia de herramientas de compilación o bibliotecas. Cómo resolver:
  • Instala las dependencias faltantes (p. ej., build-essential, libssl-dev) y vuelve a ejecutar pyenv install.

5. Errores por especificar mal la versión

Si te equivocas al indicar el número de versión en pyenv, se producirán errores. Antes de usar pyenv install, confirma con pyenv install --list que la versión existe. Cómo resolver:
  • Comprueba la lista de versiones disponibles y escribe el número correcto.

6. Conflictos entre entornos virtuales

Si usas múltiples entornos que comparten la misma versión de Python, pueden surgir conflictos de dependencias. Cómo resolver:
  • Crea un entorno virtual independiente por proyecto con virtualenv o pyenv-virtualenv para aislar completamente las dependencias.

6. Resumen y siguientes pasos

pyenv es una herramienta muy útil y potente para gestionar versiones de Python. Si trabajas con varios proyectos que requieren versiones diferentes, pyenv simplifica el cambio de versiones y hace más eficiente el manejo del entorno. Junto con virtualenv, también facilita la gestión de dependencias por proyecto y el uso de múltiples entornos en la misma máquina.

Resumen del uso de pyenv

  1. Facilidad para gestionar versiones: con pyenv alternas rápidamente versiones a nivel global o por proyecto.
  2. Uso combinado de entornos: con pyenv-virtualenv o virtualenv separas dependencias y gestionas múltiples proyectos con eficiencia.
  3. Importancia de la solución de problemas: prepárate para posibles errores o conflictos, configurando correctamente dependencias y versiones.

Siguientes pasos

  1. Más eficiencia con pyenv: una vez domines lo básico, considera combinarlo con herramientas como pipenv o poetry para simplificar aún más la gestión de dependencias y la configuración por proyecto.
  2. Adaptación a otros entornos: si usas Windows, como pyenv no está soportado directamente, evalúa WSL o herramientas alternativas como Anaconda.
  3. Pruébalo en proyectos reales: no te quedes en la teoría; integra pyenv en proyectos existentes o nuevos y comprueba cómo mejora el flujo de trabajo al crear entornos virtuales y gestionar bibliotecas.
オープンソースの力を活用する方法～Ubuntuの世界へようこそ～
Ubuntuにおけるpyenvのセットアップと活用法｜Python環境管理ガイド

目次 1 1. はじめに1.1 Pythonバージョン管理の重要性1.2 Ubuntuとpyenvの組み合わせの利点2 …