Entornos Python + Jupyter (Guía Pedagógica)

Material didáctico para entender por qué aparece el clásico "en mi ordenador funciona" y cómo resolverlo con entornos virtuales y kernels de Jupyter.

Orden recomendado de lectura

1. 01_el_problema.md
2. 02_la_caja_del_proyecto.md
3. 03_entorno_virtual_python.md
4. 04_flujo_de_trabajo.md
5. 05_errores_frecuentes.md
6. 06_que_es_un_kernel.md

Arranque rápido

Windows PowerShell

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
jupyter lab

Windows CMD

python -m venv .venv
.venv\Scripts\activate.bat
pip install -r requirements.txt
jupyter lab

macOS/Linux

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
jupyter lab

Verificación recomendada

1. Abre verificacion_jupyter.ipynb.
2. Selecciona el kernel del entorno .venv.
3. Ejecuta todas las celdas.

Mensaje para alumnos: "me da error si el repo esta vacio"

Sí puedes crear un entorno virtual aunque el repo no tenga archivos todavía. No necesitas código previo.

Ejemplo mínimo:

# Windows PowerShell
python -m venv .venv
.venv\Scripts\Activate.ps1

Si falla, muchas veces no es Python sino el editor:

1. VS Code no detectó aún el entorno.
2. El intérprete activo no es el de .venv.
3. El kernel del notebook está apuntando a otro Python.

Trucos rápidos que suelen arreglarlo:

1. Cerrar y abrir VS Code.
2. Volver a seleccionar el intérprete Python de .venv.
3. Reabrir el notebook y cambiar el kernel manualmente.
4. Reiniciar la ventana de VS Code.

Nota de versiones:

• Evita ir directamente a versiones recién publicadas de Python (por ejemplo 3.14 al salir), porque parte del ecosistema puede tardar en adaptarse.
• Para clase/proyectos guiados, suele dar menos problemas usar una versión estable y ya muy soportada (por ejemplo 3.11 o 3.12).

Notas de repositorio

• requirements.txt se versiona.
• .venv/ no se sube al repo (está en .gitignore).
• Si el kernel no aparece, revisa 05_errores_frecuentes.md.