Entornos Virtuales¶

Cuando trabajas en proyectos de Python probablemente deberías usar unentorno virtual (o un mecanismo similar) para aislar los paquetes que instalas para cada proyecto.

Crea un Proyecto¶

Primero, crea un directorio para tu proyecto.

Lo que normalmente hago es crear un directorio llamadocode dentro de mi directorio de usuario.

Y dentro de eso creo un directorio por proyecto.

// Ve al directorio principal$cd// Crea un directorio para todos tus proyectos de código$mkdircode// Entra en ese directorio de código$cdcode// Crea un directorio para este proyecto$mkdirawesome-project// Entra en ese directorio del proyecto$cdawesome-project

Crea un Entorno Virtual¶

Cuando empiezas a trabajar en un proyecto de Pythonpor primera vez, crea un entorno virtualdentro de tu proyecto.

$python-mvenv.venv

$uvvenv

Ese comando crea un nuevo entorno virtual en un directorio llamado.venv.

Activa el Entorno Virtual¶

Activa el nuevo entorno virtual para que cualquier comando de Python que ejecutes o paquete que instales lo utilicen.

$source.venv/bin/activate

$.venv\Scripts\Activate.ps1

$source.venv/Scripts/activate

Revisa que el Entorno Virtual esté Activo¶

Revisa que el entorno virtual esté activo (el comando anterior funcionó).

$whichpython/home/user/code/awesome-project/.venv/bin/python

$Get-CommandpythonC:\Users\user\code\awesome-project\.venv\Scripts\python

Actualizapip¶

Si estás usandopip para instalar paquetes (viene por defecto con Python), deberíasactualizarlo a la última versión.

Muchos errores exóticos al instalar un paquete se resuelven simplemente actualizandopip primero.

Asegúrate de que el entorno virtual esté activo (con el comando anterior) y luego ejecuta:

$python-mpipinstall--upgradepip---> 100%

$python-mensurepip--upgrade---> 100%

Añade.gitignore¶

Si estás usandoGit (deberías), añade un archivo.gitignore para excluir todo en tu.venv de Git.

$echo"*">.venv/.gitignore

*

Instala Paquetes¶

Después de activar el entorno, puedes instalar paquetes en él.

Instala Paquetes Directamente¶

Si tienes prisa y no quieres usar un archivo para declarar los requisitos de paquetes de tu proyecto, puedes instalarlos directamente.

$pipinstall"fastapi[standard]"---> 100%

$uvpipinstall"fastapi[standard]"---> 100%

Instala desderequirements.txt¶

Si tienes unrequirements.txt, ahora puedes usarlo para instalar sus paquetes.

$pipinstall-rrequirements.txt---> 100%

$uvpipinstall-rrequirements.txt---> 100%

fastapi[standard]==0.113.0pydantic==2.8.0

Ejecuta Tu Programa¶

Después de activar el entorno virtual, puedes ejecutar tu programa, y usará el Python dentro de tu entorno virtual con los paquetes que instalaste allí.

$pythonmain.pyHello World

Configura Tu Editor¶

Probablemente usarías un editor, asegúrate de configurarlo para que use el mismo entorno virtual que creaste (probablemente lo autodetectará) para que puedas obtener autocompletado y errores en línea.

Por ejemplo:

• VS Code
• PyCharm

Desactiva el Entorno Virtual¶

Una vez que hayas terminado de trabajar en tu proyecto, puedesdesactivar el entorno virtual.

$deactivate

De esta manera, cuando ejecutespython no intentará ejecutarse desde ese entorno virtual con los paquetes instalados allí.

Listo para Trabajar¶

Ahora estás listo para empezar a trabajar en tu proyecto.

Por qué Entornos Virtuales¶

Para trabajar con FastAPI necesitas instalarPython.

Después de eso, necesitaríasinstalar FastAPI y cualquier otropaquete que desees usar.

Para instalar paquetes normalmente usarías el comandopip que viene con Python (o alternativas similares).

Sin embargo, si solo usaspip directamente, los paquetes se instalarían en tuentorno global de Python (la instalación global de Python).

El Problema¶

Entonces, ¿cuál es el problema de instalar paquetes en el entorno global de Python?

En algún momento, probablemente terminarás escribiendo muchos programas diferentes que dependen dediferentes paquetes. Y algunos de estos proyectos en los que trabajas dependerán dediferentes versiones del mismo paquete. 😱

Por ejemplo, podrías crear un proyecto llamadophilosophers-stone, este programa depende de otro paquete llamadoharry, usando la versión1. Así que, necesitas instalarharry.

flowchart LR    stone(philosophers-stone) -->|requires| harry-1[harry v1]

Luego, en algún momento después, creas otro proyecto llamadoprisoner-of-azkaban, y este proyecto también depende deharry, pero este proyecto necesitaharry versión3.

flowchart LR    azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3]

Pero ahora el problema es, si instalas los paquetes globalmente (en el entorno global) en lugar de en unentorno virtual local, tendrás que elegir qué versión deharry instalar.

Si deseas ejecutarphilosophers-stone necesitarás primero instalarharry versión1, por ejemplo con:

$pipinstall"harry==1"

Y entonces terminarías conharry versión1 instalada en tu entorno global de Python.

flowchart LR    subgraph global[global env]        harry-1[harry v1]    end    subgraph stone-project[philosophers-stone project]        stone(philosophers-stone) -->|requires| harry-1    end

Pero luego si deseas ejecutarprisoner-of-azkaban, necesitarás desinstalarharry versión1 e instalarharry versión3 (o simplemente instalar la versión3 automáticamente desinstalaría la versión1).

$pipinstall"harry==3"

Y entonces terminarías conharry versión3 instalada en tu entorno global de Python.

Y si intentas ejecutarphilosophers-stone de nuevo, hay una posibilidad de queno funcione porque necesitaharry versión1.

flowchart LR    subgraph global[global env]        harry-1[<strike>harry v1</strike>]        style harry-1 fill:#ccc,stroke-dasharray: 5 5        harry-3[harry v3]    end    subgraph stone-project[philosophers-stone project]        stone(philosophers-stone) -.-x|⛔️| harry-1    end    subgraph azkaban-project[prisoner-of-azkaban project]        azkaban(prisoner-of-azkaban) --> |requires| harry-3    end

Ahora, imagina eso conmuchos otrospaquetes de los que dependen todos tusproyectos. Eso es muy difícil de manejar. Y probablemente terminarías ejecutando algunos proyectos con algunasversiones incompatibles de los paquetes, y sin saber por qué algo no está funcionando.

Además, dependiendo de tu sistema operativo (por ejemplo, Linux, Windows, macOS), podría haber venido con Python ya instalado. Y en ese caso probablemente tenía algunos paquetes preinstalados con algunas versiones específicasnecesitadas por tu sistema. Si instalas paquetes en el entorno global de Python, podrías terminarrompiendo algunos de los programas que vinieron con tu sistema operativo.

Dónde se Instalan los Paquetes¶

Cuando instalas Python, crea algunos directorios con algunos archivos en tu computadora.

Algunos de estos directorios son los encargados de tener todos los paquetes que instalas.

Cuando ejecutas:

// No ejecutes esto ahora, solo es un ejemplo 🤓$pipinstall"fastapi[standard]"---> 100%

Eso descargará un archivo comprimido con el código de FastAPI, normalmente desdePyPI.

Tambiéndescargará archivos para otros paquetes de los que depende FastAPI.

Luego,extraerá todos esos archivos y los pondrá en un directorio en tu computadora.

Por defecto, pondrá esos archivos descargados y extraídos en el directorio que viene con tu instalación de Python, eso es elentorno global.

Qué son los Entornos Virtuales¶

La solución a los problemas de tener todos los paquetes en el entorno global es usar unentorno virtual para cada proyecto en el que trabajas.

Un entorno virtual es undirectorio, muy similar al global, donde puedes instalar los paquetes para un proyecto.

De esta manera, cada proyecto tendrá su propio entorno virtual (directorio.venv) con sus propios paquetes.

flowchart TB    subgraph stone-project[philosophers-stone project]        stone(philosophers-stone) --->|requires| harry-1        subgraph venv1[.venv]            harry-1[harry v1]        end    end    subgraph azkaban-project[prisoner-of-azkaban project]        azkaban(prisoner-of-azkaban) --->|requires| harry-3        subgraph venv2[.venv]            harry-3[harry v3]        end    end    stone-project ~~~ azkaban-project

Qué Significa Activar un Entorno Virtual¶

Cuando activas un entorno virtual, por ejemplo con:

$source.venv/bin/activate

$.venv\Scripts\Activate.ps1

$source.venv/Scripts/activate

Ese comando creará o modificará algunasvariables de entorno que estarán disponibles para los siguientes comandos.

Una de esas variables es la variablePATH.

Activar un entorno virtual agrega su path.venv/bin (en Linux y macOS) o.venv\Scripts (en Windows) a la variable de entornoPATH.

Digamos que antes de activar el entorno, la variablePATH se veía así:

/usr/bin:/bin:/usr/sbin:/sbin

C:\Windows\System32

Después de activar el entorno virtual, la variablePATH se vería algo así:

/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin

/home/user/code/awesome-project/.venv/bin

/home/user/code/awesome-project/.venv/bin/python

C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32

C:\Users\user\code\awesome-project\.venv\Scripts

C:\Users\user\code\awesome-project\.venv\Scripts\python

Un detalle importante es que pondrá el path del entorno virtual alcomienzo de la variablePATH. El sistema lo encontraráantes que cualquier otro Python disponible. De esta manera, cuando ejecutespython, utilizará el Pythondel entorno virtual en lugar de cualquier otropython (por ejemplo, unpython de un entorno global).

Activar un entorno virtual también cambia un par de otras cosas, pero esta es una de las cosas más importantes que hace.

Revisando un Entorno Virtual¶

Cuando revisas si un entorno virtual está activo, por ejemplo con:

$whichpython/home/user/code/awesome-project/.venv/bin/python

$Get-CommandpythonC:\Users\user\code\awesome-project\.venv\Scripts\python

Eso significa que el programapython que se utilizará es el que estáen el entorno virtual.

Usaswhich en Linux y macOS yGet-Command en Windows PowerShell.

La forma en que funciona ese comando es que irá y revisará la variable de entornoPATH, pasando porcada path en orden, buscando el programa llamadopython. Una vez que lo encuentre, temostrará el path a ese programa.

La parte más importante es que cuando llamas apython, ese es el exacto "python" que será ejecutado.

Así que, puedes confirmar si estás en el entorno virtual correcto.

Por qué Desactivar un Entorno Virtual¶

Por ejemplo, podrías estar trabajando en un proyectophilosophers-stone,activar ese entorno virtual, instalar paquetes y trabajar con ese entorno.

Y luego quieres trabajar enotro proyectoprisoner-of-azkaban.

Vas a ese proyecto:

$cd~/code/prisoner-of-azkaban

Si no desactivas el entorno virtual paraphilosophers-stone, cuando ejecutespython en el terminal, intentará usar el Python dephilosophers-stone.

$cd~/code/prisoner-of-azkaban$pythonmain.py// Error importando sirius, no está instalado 😱Traceback (most recent call last):    File "main.py", line 1, in <module>        import sirius

Pero si desactivas el entorno virtual y activas el nuevo paraprisoner-of-askaban entonces cuando ejecutespython utilizará el Python del entorno virtual enprisoner-of-azkaban.

$cd~/code/prisoner-of-azkaban// No necesitas estar en el directorio antiguo para desactivar, puedes hacerlo donde sea que estés, incluso después de ir al otro proyecto 😎$deactivate// Activa el entorno virtual en prisoner-of-azkaban/.venv 🚀$source.venv/bin/activate// Ahora cuando ejecutes python, encontrará el paquete sirius instalado en este entorno virtual ✨$pythonmain.pyI solemnly swear 🐺

Alternativas¶

Esta es una guía simple para comenzar y enseñarte cómo funciona todopor debajo.

Hay muchasalternativas para gestionar entornos virtuales, dependencias de paquetes (requisitos), proyectos.

Una vez que estés listo y quieras usar una herramienta paragestionar todo el proyecto, dependencias de paquetes, entornos virtuales, etc. Te sugeriría probaruv.

uv puede hacer muchas cosas, puede:

• Instalar Python por ti, incluyendo diferentes versiones
• Gestionar elentorno virtual para tus proyectos
• Instalarpaquetes
• Gestionardependencias y versiones de paquetes para tu proyecto
• Asegurarse de que tengas un conjuntoexacto de paquetes y versiones para instalar, incluidas sus dependencias, para que puedas estar seguro de que puedes ejecutar tu proyecto en producción exactamente igual que en tu computadora mientras desarrollas, esto se llamalocking
• Y muchas otras cosas

Conclusión¶

Si leíste y comprendiste todo esto, ahorasabes mucho más sobre entornos virtuales que muchos desarrolladores por ahí. 🤓

Conocer estos detalles probablemente te será útil en el futuro cuando estés depurando algo que parece complejo, pero sabráscómo funciona todo por debajo. 😎