Entornos virtuales
Un entorno virtual es una carpeta que contiene una instalación de Python aislada del resto de tu sistema. Cada proyecto tiene sus propias versiones de las librerías, sin interferir con otros proyectos ni con el Python del sistema.
Analogía · Una caja de herramientas por proyecto
Imagina que eres electricista y tienes una caja de herramientas para cada obra: una para el edificio A y otra para el edificio B. Si cambias las herramientas de la caja A, las de B no se ven afectadas. El entorno virtual funciona igual: FastAPI 0.115 para Cargo Track no afecta a otro proyecto que use una versión diferente.
Crear el entorno virtual
Abre una terminal, navega a la carpeta donde vas a guardar el proyecto y ejecuta:
- Linux
- macOS
- Windows
Esto crea una carpeta llamada venv/ con una copia aislada de Python. Ahora actívala:
- Linux
- macOS
- Windows
Sabes que el entorno está activo cuando ves (venv) al inicio de la línea en tu terminal.
Instalar las dependencias
Con el entorno activo, instala todo lo que vamos a necesitar en este taller:
pip install fastapi==0.115.0 uvicorn==0.30.0 sqlmodel==0.0.21 httpx==0.27.0 streamlit==1.40.0 python-jose[cryptography]==3.3.0 email-validator==2.1.0
Algo va a fallar... · Trabajar sin activar el entorno
Cierra la terminal y ábrela de nuevo sin activar el entorno virtual. Luego intenta importar FastAPI:
python -c "import fastapi"
Cómo resolverlo
Si no activaste el entorno, vas a ver:
ModuleNotFoundError: No module named 'fastapi'
Este es el error más común al trabajar con entornos virtuales. FastAPI está instalado dentro de venv/, pero Python no sabe dónde buscarlo porque el entorno no está activo.
La solución: activa el entorno antes de cualquier cosa. Repite el comando de activación según tu sistema operativo y vuelve a intentar la importación. Desde ahora, lo primero que haces al abrir una terminal para trabajar en Cargo Track es activar el entorno.
Guardar las dependencias
Guarda la lista de paquetes instalados en un archivo para que cualquier persona pueda reproducir el entorno:
pip freeze > requirements.txt
Ojo
Agrega la carpeta venv/ a tu .gitignore si usas Git. Nunca subas el entorno virtual al repositorio: es pesado y cada persona debe crear el suyo con pip install -r requirements.txt.
Checkpoint
Con el entorno activo, ejecuta pip list y verifica que ves fastapi, uvicorn, sqlmodel y streamlit en la lista. Si los ves, el entorno está listo para los siguientes pasos.
Guarda tu progreso
Haz un commit con los cambios de este paso:
git add requirements.txt
git commit -m "chore: agregar requirements.txt con dependencias del proyecto"