Cómo configurar Jupyter Notebook con Docker y VS Code Dev Containers

Si eres como yo, un informático al que le apasionan las matemáticas y todo lo relacionado con la inteligencia artificial, probablemente también hayas experimentado algunos problemas a la hora de configurar entornos de desarrollo.Durante el cursado de una maestria, me di cuenta de lo importante que es tener un entorno reproducible y portable para trabajar con Python, machine learning y análisis de datos. ¿Cuántas veces te habrá pasado el clásico problema de “funciona en mi máquina pero no en la tuya”?

Docker resuelve exactamente este problema creando entornos aislados y reproducibles. En este tutorial, te mostraré cómo configurar Jupyter con Docker y aprovechar las Dev Containers de VS Code para tener una experiencia de desarrollo fluida y profesional.

¿Por qué no usar Google Colab u otras alternativas?

Existen otras opciones excelentes como Google Colab (Google Cuadernos), Kaggle Notebooks, Azure Notebooks o Deepnote. Estas plataformas son geniales y tienen sus ventajas:

• No requieren instalación
• Acceso a GPUs gratuitas (en algunos casos)
• Colaboración en tiempo real
• Fáciles de compartir

Sin embargo, la configuración con Docker local tiene beneficios únicos:

• Privacidad: Tus datos no salen de tu máquina
• Sin límites de tiempo: No hay sesiones que expiren
• Control total: Instala cualquier librería o versión que necesites
• Offline: Trabaja sin internet
• Entornos corporativos: Ideal cuando trabajas con datos sensibles o en empresas con políticas de seguridad estrictas

Si trabajas con datos confidenciales, proyectos de producción o simplemente prefieres tener control total de tu entorno, esta es tu mejor opción.

¿Qué necesitas instalar?

Antes de empezar, asegúrate de tener instalado:

1. Docker Desktop: Descarga aquí
2. Visual Studio Code: Descarga aquí
3. Extensión Dev Containers: Busca “Dev Containers” en el marketplace de VS Code
4. Extensión Python: Busca “Python” (publicada por Microsoft)
5. Extensión Jupyter: Busca “Jupyter” (publicada por Microsoft)

Estructura del proyecto

Organiza tu proyecto con la siguiente estructura:

proyecto/
├── docker-compose.yml
├── app/
│   └── (tus notebooks y código aquí)
├── ia/
│   ├── Dockerfile
│   └── requirements.txt
└── .devcontainer/
    └── devcontainer.json

Paso 1: Crear el Dockerfile

Crea un archivo Dockerfile en la carpeta ia/:

FROM python:3.10-slim

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y \
    procps \
    gcc \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /usr/src/app

COPY requirements.txt .

RUN pip install --upgrade pip
RUN pip install -r requirements.txt

# 🔥 IMPORTANTE: Instalar Jupyter y ipykernel
RUN pip install jupyter ipykernel

COPY . .

ENV PYTHONPATH=/usr/src/app

¿Por qué estos componentes?

• python:3.10-slim: Imagen base ligera de Python
• gcc y procps: Herramientas necesarias para compilar algunas librerías científicas
• jupyter e ipykernel: El núcleo de Jupyter para ejecutar notebooks

Paso 2: Definir las dependencias

Crea un archivo requirements.txt en la carpeta ia/ con tus librerías:

fastapi==0.59.0
uvicorn==0.11.5
numpy 
scipy 
pandas 
matplotlib
scikit-learn
nltk
pymongo
scikit-plot
requests
statsmodels
seaborn
sympy

Estas son librerías comunes para ciencia de datos y machine learning. Ajusta según tus necesidades.

Paso 3: Configurar Docker Compose

Crea docker-compose.yml en la raíz del proyecto:

version: '3.10'
services:
  ia:
    build:
      context: ./ia
    ports:
      - "8010:8010"
    tty: true
    volumes:
     - ./app:/usr/src/app
    extra_hosts:
      - "host.docker.internal:host-gateway"

Puntos clave:

• volumes: Sincroniza tu carpeta local app/ con el contenedor
• ports: Mapea el puerto 8010 (puedes usar 8888 que es el puerto por defecto de Jupyter)
• tty: true: Mantiene el contenedor ejecutándose

Paso 4: Configurar Dev Container para VS Code

Crea la carpeta .devcontainer/ y dentro el archivo devcontainer.json:

{
	"name": "Jupyter con Docker",
	"dockerComposeFile": [
		"../docker-compose.yml"
	],
	"service": "ia",
	"workspaceFolder": "/usr/src/app",
	"customizations": {
		"vscode": {
			"extensions": [
				"ms-python.python",
				"ms-toolsai.jupyter",
				"ms-toolsai.jupyter-keymap",
				"ms-toolsai.jupyter-renderers"
			]
		}
	}
}

¿Qué hace esto?

• Conecta VS Code directamente con tu contenedor Docker
• Instala automáticamente las extensiones de Python y Jupyter dentro del contenedor
• Abre tu workspace en la carpeta correcta del contenedor

Paso 5: Iniciar el entorno

Opción A: Usar Docker Compose directamente

docker-compose up --build

Opción B: Usar Dev Containers (Recomendado)

1. Abre VS Code en la carpeta de tu proyecto
2. Presiona F1 o Ctrl+Shift+P
3. Escribe “Dev Containers: Reopen in Container”
4. Espera a que el contenedor se construya y conecte

¡Y listo! Ahora tienes un entorno completamente funcional.

Trabajando con Jupyter Notebooks

Una vez dentro del Dev Container:

1. Crea un nuevo archivo .ipynb en la carpeta app/
2. VS Code detectará automáticamente el kernel de Python en el contenedor
3. Importante: Cuando abras un notebook, VS Code te pedirá que selecciones un kernel. Haz clic en “Select Kernel” en la esquina superior derecha
4. Selecciona el kernel del contenedor: /usr/local/bin/python (Python 3.10.20) - Este es el Python instalado dentro del contenedor Docker
5. ¡Comienza a escribir código!

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

# Tu código aquí
df = pd.DataFrame({'x': range(10), 'y': np.random.rand(10)})
df.plot(x='x', y='y')
plt.show()

Ventajas de este setup

✅ Reproducibilidad: Mismo entorno en cualquier máquina
✅ Aislamiento: No contaminas tu sistema con dependencias
✅ Portabilidad: Comparte el proyecto con tu equipo fácilmente
✅ Integración: Todo funciona dentro de VS Code, sin necesidad del navegador
✅ Control de versiones: Dockerfiles y requirements en Git

Comandos útiles

# Reconstruir el contenedor después de cambios en requirements.txt
docker-compose up --build

# Ver contenedores en ejecución
docker ps

# Detener contenedores
docker-compose down

# Eliminar contenedores y volúmenes
docker-compose down -v

Solución de problemas comunes

El kernel no aparece en VS Code

• Verifica que las extensiones de Jupyter y Python estén instaladas
• Recarga la ventana: Ctrl+Shift+P → “Reload Window”
• Asegúrate de seleccionar el kernel correcto: /usr/local/bin/python (Python 3.10.20) del contenedor, no el Python de tu máquina local

Los cambios en requirements.txt no se aplican

• Reconstruye el contenedor: docker-compose up --build

Error de permisos en archivos

• Ajusta los permisos del volumen en docker-compose.yml

Conclusión

Configurar Jupyter con Docker y VS Code Dev Containers puede parecer complejo al principio, pero una vez que lo tienes funcionando, la experiencia de desarrollo mejora enormemente. Tienes un entorno reproducible, portable y profesional que puedes compartir con tu equipo o usar en diferentes máquinas sin problemas.

¿Tienes preguntas o mejoras? ¡Déjame un comentario!

---

Tags: #Docker #Jupyter #Python #DataScience #VSCode #DevContainers