Entornos Virtuales¶

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

Crear un Proyecto¶

Primero, crea un directorio para tu proyecto.

Lo que normalmente hago es crear un directorio llamado code dentro de mi directorio home/user.

Y dentro de ese creo un directorio por proyecto.

cd
mkdir code
cd code
mkdir awesome-project
cd awesome-project
fast →💬 Go to the home directorycd💬 Create a directory for all your code projectsmkdir code💬 Enter into that code directorycd code💬 Create a directory for this projectmkdir awesome-project💬 Enter into that project directorycd awesome-project
restart ↻

Crear un Entorno Virtual¶

Cuando empiezas a trabajar en un proyecto de Python por primera vez, crea un entorno virtual dentro de tu proyecto.

python -m venv .venv
fast →python -m venv .venv
restart ↻

uv venv
fast →uv venv
restart ↻

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

Activar el Entorno Virtual¶

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

source .venv/bin/activate
fast →source .venv/bin/activate
restart ↻

.venv\Scripts\Activate.ps1
fast →.venv\Scripts\Activate.ps1
restart ↻

source .venv/Scripts/activate
fast →source .venv/Scripts/activate
restart ↻

Verificar que el Entorno Virtual esté Activo¶

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

which python
fast →which python
/home/user/code/awesome-project/.venv/bin/python

restart ↻

Get-Command python
fast →Get-Command python
C:\Users\user\code\awesome-project\.venv\Scripts\python

restart ↻

Actualizar pip¶

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

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

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

python -m pip install --upgrade pip
fast →python -m pip install --upgrade pip

restart ↻

python -m ensurepip --upgrade
fast →python -m ensurepip --upgrade

restart ↻

Añadir .gitignore¶

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

echo "*" > .venv/.gitignore
fast →echo "*" > .venv/.gitignore
restart ↻

*

Instalar Paquetes¶

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

Instalar Paquetes Directamente¶

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

pip install "fastapi[standard]"
fast →pip install "fastapi[standard]"

restart ↻

uv pip install "fastapi[standard]"
fast →uv pip install "fastapi[standard]"████████████████████████████████████████ 100%
restart ↻

Instalar desde requirements.txt¶

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

pip install -r requirements.txt
fast →pip install -r requirements.txt
restart ↻

uv pip install -r requirements.txt
fast →uv pip install -r requirements.txt████████████████████████████████████████ 100%
restart ↻

fastapi[standard]==0.113.0
pydantic==2.8.0

Ejecutar 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 ahí.

python main.py
fast →python main.py
Hello World

restart ↻

Configurar Tu Editor¶

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

Por ejemplo:

• VS Code
• PyCharm

Desactivar el Entorno Virtual¶

Una vez que terminas de trabajar en tu proyecto puedes desactivar el entorno virtual.

deactivate
fast →deactivate
restart ↻

De esta manera, cuando ejecutes python no intentará ejecutarlo desde ese entorno virtual con los paquetes instalados ahí.

Listo para Trabajar¶

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

Por qué Entornos Virtuales¶

Para trabajar con FastAPI necesitas instalar Python.

Después de eso, necesitarías instalar FastAPI y cualquier otro paquete que quieras usar.

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

Sin embargo, si simplemente usas pip directamente, los paquetes se instalarían en tu entorno global de Python (la instalación global de Python).

El Problema¶

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

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

Por ejemplo, podrías crear un proyecto llamado philosophers-stone, este programa depende de otro paquete llamado harry, usando la versión 1. Así que necesitas instalar harry.

Luego, en algún momento después, creas otro proyecto llamado prisoner-of-azkaban, y este proyecto también depende de harry, pero este proyecto necesita harry versión 3.

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

Si quieres ejecutar philosophers-stone necesitarás primero instalar harry versión 1, por ejemplo con:

pip install "harry==1"
fast →pip install "harry==1"
restart ↻

Y entonces terminarías con harry versión 1 instalado en tu entorno global de Python.

Pero entonces si quieres ejecutar prisoner-of-azkaban, necesitarás desinstalar harry versión 1 e instalar harry versión 3 (o simplemente instalar la versión 3 desinstalaría automáticamente la versión 1).

pip install "harry==3"
fast →pip install "harry==3"
restart ↻

Y entonces terminarías con harry versión 3 instalado en tu entorno global de Python.

Y si intentas ejecutar philosophers-stone nuevamente, hay una posibilidad de que no funcione porque necesita harry versión 1.

Ahora, imagina eso con muchos otros paquetes de los que todos tus proyectos dependen. Eso es muy difícil de manejar. Y probablemente terminarías ejecutando algunos proyectos con algunas versiones incompatibles de los paquetes, y sin saber por qué algo no funciona.

Además, dependiendo de tu sistema operativo (ej. Linux, Windows, macOS), podría haber venido con Python ya instalado. Y en ese caso probablemente tenía algunos paquetes pre-instalados con algunas versiones específicas necesarias para tu sistema. Si instalas paquetes en el entorno global de Python, podrías terminar rompiendo algunos de los programas que venían con tu sistema operativo.

Dónde se Instalan los Paquetes¶

Cuando instalas Python, este 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:

pip install "fastapi[standard]"
fast →💬 Don't run this now, it's just an example 🤓pip install "fastapi[standard]"
restart ↻

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

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

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, ese es el entorno global.

Qué son los Entornos Virtuales¶

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

Un entorno virtual es un directorio, 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.

Qué Significa Activar un Entorno Virtual¶

Cuando activas un entorno virtual, por ejemplo con:

source .venv/bin/activate
fast →source .venv/bin/activate
restart ↻

.venv\Scripts\Activate.ps1
fast →.venv\Scripts\Activate.ps1
restart ↻

source .venv/Scripts/activate
fast →source .venv/Scripts/activate
restart ↻

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

Una de esas variables es la variable PATH.

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

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

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

C:\Windows\System32

Después de activar el entorno virtual, la variable PATH 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 al principio de la variable PATH. El sistema lo encontrará antes de encontrar cualquier otro Python disponible. De esta manera, cuando ejecutes python, usará el Python del entorno virtual en lugar de cualquier otro python (por ejemplo, un python de un entorno global).

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

Verificar un Entorno Virtual¶

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

which python
fast →which python
/home/user/code/awesome-project/.venv/bin/python

restart ↻

Get-Command python
fast →Get-Command python
C:\Users\user\code\awesome-project\.venv\Scripts\python

restart ↻

Eso significa que el programa python que se usará es el que está en el entorno virtual.

Usas which en Linux y macOS y Get-Command en Windows PowerShell.

La forma en que funciona ese comando es que irá y revisará en la variable de entorno PATH, recorriendo cada path en orden, buscando el programa llamado python. Una vez que lo encuentra, te mostrará el path a ese programa.

La parte más importante es que cuando llamas a python, ese es el exacto "python" que se ejecutará.

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

Por qué Desactivar un Entorno Virtual¶

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

Y luego quieres trabajar en otro proyecto prisoner-of-azkaban.

Vas a ese proyecto:

cd ~/code/prisoner-of-azkaban
fast →cd ~/code/prisoner-of-azkaban
restart ↻

Si no desactivas el entorno virtual de philosophers-stone, cuando ejecutes python en la terminal, intentará usar el Python de philosophers-stone.

cd ~/code/prisoner-of-azkaban
python main.py
fast →cd ~/code/prisoner-of-azkaban
python main.py
💬 Error importing sirius, it's not installed 😱Traceback (most recent call last):
    File "main.py", line 1, in 
        import sirius

restart ↻

Pero si desactivas el entorno virtual y activas el nuevo para prisoner-of-azkaban entonces cuando ejecutes python usará el Python del entorno virtual en prisoner-of-azkaban.

cd ~/code/prisoner-of-azkaban
deactivate
source .venv/bin/activate
python main.py
fast →cd ~/code/prisoner-of-azkaban
💬 You don't need to be in the old directory to deactivate, you can do it wherever you are, even after going to the other project 😎deactivate
💬 Activate the virtual environment in prisoner-of-azkaban/.venv 🚀source .venv/bin/activate
💬 Now when you run python, it will find the package sirius installed in this virtual environment ✨python main.py
I solemnly swear 🐺

restart ↻

Alternativas¶

Esta es una guía simple para que empieces y te enseñe cómo funciona todo por debajo.

Hay muchas alternativas para manejar entornos virtuales, dependencias de paquetes (requisitos), proyectos.

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

uv puede hacer muchas cosas, puede:

• Instalar Python por ti, incluyendo diferentes versiones
• Manejar el entorno virtual para tus proyectos
• Instalar paquetes
• Manejar las dependencias y versiones de paquetes para tu proyecto
• Asegurar que tengas un conjunto exacto de paquetes y versiones para instalar, incluyendo 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 llama locking
• Y muchas otras cosas

Conclusión¶

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

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