Cuadernos marimo¶
marimo es el formato de cuaderno de Python que usamos en los dos módulos del curso. Los ejemplos, las prácticas y los proyectos se entregan como archivos marimo para que el código, las dependencias y el orden lógico de cálculo queden visibles y versionables.
Esta es la introducción común. Después de leerla deberías poder crear un cuaderno, abrirlo en VS Code, interpretar el recálculo de sus celdas y comprobarlo antes de entregarlo.
Qué aprenderás¶
Al terminar esta guía podrás:
- explicar qué significa que un cuaderno sea reactivo;
- crear y abrir un archivo
.pyde marimo dentro de VS Code; - separar celdas de código, Markdown estático y Markdown dinámico;
- conectar un widget con una celda dependiente;
- revisar, ejecutar, convertir y exportar un cuaderno sin confundir esos formatos con la entrega del curso.
El modelo mental: un grafo de celdas¶
Un cuaderno marimo es un programa Python dividido en celdas. Cada celda se analiza como una función: sus variables de entrada son los nombres que usa y sus variables de salida son los nombres que define. marimo usa esas dependencias para construir un grafo y recalcula las celdas afectadas cuando cambia una entrada.
La consecuencia práctica es que no debes depender de haber ejecutado antes una
celda “por casualidad”. Si una celda necesita tabla, debe existir una celda
visible que defina tabla.
Por qué marimo y no Jupyter
- Menos estado oculto. En un cuaderno basado en ejecución manual puedes ejecutar celdas en un orden distinto al que aparece en el archivo. En marimo, las dependencias visibles dirigen el recálculo.
- Resultados reactivos. Si cambia una variable, se actualizan las celdas que dependen de ella, como en una hoja de cálculo.
- Fuente Python. El cuaderno se guarda como un archivo
.py, no como un contenedor binario de resultados. Las sesiones y metadatos que genere la integración pueden vivir en__marimo__/, que este proyecto ignora.
La reactividad no hace reproducibles los datos externos ni elimina la
aleatoriedad. Debes fijar semillas cuando corresponda, declarar dependencias
con uv y explicar de dónde proceden los datos.
Instalar y comprobar¶
En un proyecto nuevo, añade marimo como dependencia de ejecución:
En este repositorio ya está declarado en pyproject.toml; después de clonar o
cambiar de equipo basta con:
Salida esperada en el entorno actual del curso:
La versión concreta puede cambiar cuando se actualice uv.lock. Ejecutar con
uv run garantiza que se usa el marimo del proyecto, no una instalación global.
Para el resto del entorno, consulta uv.
Trabajar en VS Code¶
El flujo recomendado es el siguiente:
- Instala la extensión oficial de marimo de marimo-team desde la vista de
extensiones (
Ctrl+Shift+X), si aún no la tienes. - Abre la carpeta completa del proyecto en VS Code.
- Comprueba que
marimoestá en el proyecto (uv run marimo --version); si no, añádelo conuv add marimo. - Comprueba que VS Code usa el intérprete de
.venv(Python: Select Interpreter). - Abre un archivo
.pycomo cuaderno marimo desde la paleta de comandos o con el botón de marimo del editor.
Un archivo .py puede abrirse como texto Python o como cuaderno interactivo.
Son dos vistas del mismo archivo: la vista de cuaderno ofrece las celdas, los
widgets y la ejecución reactiva; el archivo sigue siendo código versionable.
Consulta VS Code si el intérprete o la extensión no aparecen.
Primer cuaderno¶
Crea uno desde la paleta de comandos (Ctrl+Shift+P): busca marimo y
ejecuta New marimo notebook. Llámalo hola_marimo.py.
La primera celda de un cuaderno nuevo suele contener ya import marimo as mo.
Déjala así: la necesitarás más abajo.
En la siguiente celda de código escribe:
En otra celda escribe:
La última expresión de una celda se muestra sin necesidad de print.
Salida esperada:
Ahora cambia nombre a "Luis" en la primera celda y ejecútala. La celda de
mensaje se recalcula sola porque usa nombre: esa es la evidencia observable
de la reactividad.
Elegir el kernel correcto¶
El kernel es el intérprete que ejecuta el cuaderno. La primera vez que
ejecutes una celda o pulses Ejecutar todo, selecciona el Python del entorno
virtual del proyecto, normalmente Python 3.14 (.venv).
En Linux y macOS suele ser .venv/bin/python; en Windows,
.venv\Scripts\python.exe. No elijas el Python global: podría no tener las
dependencias de pyproject.toml.
Si el entorno no aparece, ejecuta uv sync, vuelve a abrir la paleta y usa
Python: Select Interpreter. El intérprete elegido para VS Code y el kernel
de marimo deben apuntar al mismo .venv.
Markdown: texto y resultados¶
Markdown es texto plano con una sintaxis ligera para crear títulos, listas, enlaces, tablas y énfasis. En marimo se puede escribir directamente en una celda Markdown cuando el texto es estático:
# Bienvenida
Este cuaderno contiene texto formateado.
## Qué estamos viendo
- **Celdas de código** y de **Markdown**
- El *recálculo reactivo*
| Concepto | Estado |
|----------|:------:|
| Celdas de código | Listas |
| Celdas de Markdown | Listas |
La celda se muestra formateada al ejecutarla. Para este caso no hace falta
importar marimo ni escribir mo.md().
Cuando el texto depende de variables Python, usa una celda de código y
mo.md(). mo es el nombre corto con el que se importa marimo en la primera
celda del cuaderno:
Salida esperada: una celda Markdown que muestra el saludo en negrita y se
actualiza cuando cambia mensaje.
Para ampliar la sintaxis, consulta la Guía de Markdown, la especificación CommonMark y la documentación de marimo.
Widgets reactivos¶
Los widgets permiten explorar un parámetro sin editar el código en cada prueba. En una celda de código:
La celda muestra el deslizador. El objeto numero es el control; su valor
actual se consulta con numero.value. Una celda posterior puede depender de él:
Salida esperada: con el deslizador en 3, la celda muestra 9; al moverlo
a 4, muestra 16 sin ejecutar manualmente la celda de cuadrado.
Cada nombre se define en una sola celda
marimo no permite que dos celdas definan la misma variable, y eso incluye
los import. Si escribes import marimo as mo en dos celdas, el cuaderno
muestra un error de definición múltiple. Importa cada librería una sola
vez, normalmente en una celda al principio, y úsala desde el resto.
Cómo organizar un cuaderno¶
Una estructura sencilla para las prácticas es:
- Contexto y objetivo: qué pregunta se quiere responder.
- Parámetros e imports: dependencias y opciones que se pueden cambiar.
- Carga de datos: origen, formato y comprobaciones iniciales.
- Transformación: operaciones que producen tablas o variables nuevas.
- Resultado: métricas, gráficos o predicciones.
- Conclusión: qué se observa, qué limitaciones quedan y qué decisión se justificaría.
Mantén una idea principal por celda y usa nombres descriptivos. Si necesitas
una versión modificada de una variable, dale otro nombre (ventas →
ventas_limpias) en lugar de redefinirla en otra celda. Si el resultado depende de datos externos,
documenta la ruta, la versión o la forma de obtenerlos. Si usa aleatoriedad,
fija una semilla y explica por qué.
Comprobar, ejecutar y convertir¶
El editor de VS Code es el flujo normal, pero la terminal permite comprobar el cuaderno de forma repetible:
| Comando | Uso |
|---|---|
uv run marimo check cuaderno.py |
Analiza dependencias y diagnósticos del cuaderno |
uv run marimo edit |
Abre el editor web y lista los cuadernos del proyecto |
uv run marimo edit cuaderno.py |
Abre un cuaderno concreto en el editor web |
uv run marimo run cuaderno.py |
Ejecuta el cuaderno como una aplicación |
uv run marimo new |
Crea un cuaderno vacío desde la terminal |
uv run marimo tutorial intro |
Abre el tutorial oficial |
Antes de entregar, ejecuta:
Salida esperada: no aparecen diagnósticos y el comando termina con código
0. Si hay un error de dependencia, corrígelo en el cuaderno o en el proyecto;
no lo tapes ejecutando las celdas en un orden especial.
Convertir un cuaderno de Jupyter¶
La conversión sirve para recuperar material existente, no cambia el formato de entrega del curso:
Después de convertirlo, abre el .py en VS Code y revisa sus dependencias,
transformaciones y nombres. La conversión puede perder salidas guardadas y
requiere adaptar código que modificaba variables entre celdas.
Exportar¶
Puedes compartir una versión HTML estática del resultado:
Efecto observable: aparece hola_marimo.html en la carpeta indicada. La
exportación sirve para compartir resultados; el formato fuente y de entrega
sigue siendo el cuaderno marimo .py.
Otros destinos siguen el mismo patrón, como md, ipynb o pdf. La
exportación a ipynb es para interoperabilidad, no para sustituir el formato
del curso.
Versionar y compartir¶
Versiona el archivo .py del cuaderno junto con los datos pequeños o las
instrucciones para obtener datos externos. No subas secretos, entornos
virtuales ni la carpeta __marimo__/: este proyecto ya ignora esos artefactos
en .gitignore. Usa Git para revisar el diff antes de entregar; consulta
Git y GitHub.
Problemas habituales¶
| Síntoma | Causa probable | Solución inicial |
|---|---|---|
| El archivo se abre como texto | No se ha abierto como cuaderno marimo | Usa la paleta, busca marimo y elige abrirlo como notebook |
| No aparece el kernel del proyecto | Falta .venv o VS Code usa otro intérprete |
Ejecuta uv sync y selecciona el Python de .venv |
ModuleNotFoundError |
El paquete no está declarado o el kernel es incorrecto | Añade el paquete con uv add y selecciona el kernel del proyecto |
| Una celda no puede usar una variable | La variable no está definida en una celda dependiente | Crea una celda que la defina y revisa el grafo visible |
| El resultado cambia al repetir | Hay aleatoriedad o datos externos no fijados | Usa una semilla, registra el origen de datos y documenta el supuesto |
| El cuaderno convertido falla | El código dependía del orden manual de ejecución | Divide las transformaciones y declara explícitamente las dependencias |
Comprobación final¶
Un cuaderno está preparado para entregar cuando puedes responder a estas tres preguntas:
- ¿Qué celda define cada variable importante?
- ¿Qué cambia cuando modifico el parámetro principal?
- ¿Puedo ejecutar el cuaderno desde cero con el kernel y las dependencias del proyecto?
La evidencia técnica mínima es:
Sin diagnósticos no significa que el análisis sea correcto: todavía debes interpretar los resultados, justificar decisiones y comprobar los datos.
Para saber más
La documentación oficial y la web marimo.io incluyen tutoriales, ejemplos y la referencia completa de la API.
Siguiente paso¶
Sigue con Git y GitHub para versionar tus cuadernos.