Entorno de trabajo¶

Esta página es la puerta de entrada al curso. Te lleva desde la instalación de las herramientas hasta una comprobación observable del proyecto.

En este recorrido usamos Python 3.14, el gestor de proyectos uv, Git y cuadernos interactivos marimo. La referencia completa de uv está en uv; aquí solo necesitas el recorrido inicial.

Antes de empezar: la terminal¶

Casi todo lo que se hace en esta página se escribe en una terminal (también llamada consola o línea de comandos): una ventana donde escribes órdenes de texto y el sistema responde con texto. Cada orden se escribe en una línea y se ejecuta al pulsar Intro.

Cuando tengas VS Code instalado, usarás la terminal integrada del editor (Terminal → Nueva terminal), que es la misma terminal dentro de la ventana del editor. En los bloques de esta página, cada línea es una orden distinta: escríbelas de una en una y espera a que termine cada una.

El orden recomendado de instalación es: VS Code (ver VS Code), Git (ver Git y GitHub) y uv (en esta página). uv se encarga después de descargar Python 3.14: no necesitas instalar Python por separado.

Resultado esperado¶

Al terminar esta página deberías poder:

• abrir la carpeta correcta del proyecto;
• tener un Python y un entorno virtual .venv asociados al proyecto;
• sincronizar las dependencias desde pyproject.toml y uv.lock;
• ejecutar una comprobación con uv run sin depender del Python global;
• diagnosticar los problemas básicos de ruta, Python y dependencias.

La evidencia mínima de que el entorno está preparado será similar a:

uv 0.10.4
Python 3.14.3
Dependencias principales disponibles

Las versiones concretas pueden cambiar al actualizar el lockfile, pero el comando debe terminar sin errores.

Elige tu punto de partida¶

Herramientas del curso¶

El proyecto completo del curso declara además las librerías de las unidades posteriores (polars, duckdb, FastAPI, PyTorch, MLflow…). La lista vigente está en su pyproject.toml; no tienes que instalar cada paquete por separado después de clonar el repositorio.

Por qué estas herramientas y no otras¶

Ninguna de las elecciones es casual; conviene que sepas qué alternativas existen y por qué las descartamos:

• uv frente a pip + venv + requirements.txt. Con pip y venv gestionas tres cosas por separado (intérprete, entorno y dependencias) y el archivo de requisitos no fija las versiones exactas de todo lo que se instala, así que dos estudiantes con el mismo requirements.txt pueden acabar con entornos distintos. uv lo une todo en un flujo: instala intérpretes, crea el entorno y fija cada versión en uv.lock, de modo que uv sync reproduce el mismo entorno en cualquier equipo. Además es extremadamente rápido. Es la herramienta más reciente de la lista y evoluciona rápido, pero su modo proyecto (pyproject.toml + lockfile) es el estándar hacia el que se mueve el ecosistema Python.
• VS Code frente a otros editores. Es gratuito, multiplataforma y con la extensión de Python (y la de marimo) cubre editor, depurador, terminal y control de versiones en una sola aplicación. Alternativas como PyCharm son excelentes pero de pago en su versión completa; el objetivo del curso es que sepas trabajar con el entorno que encontrarás en la mayoría de equipos.
• Git + GitHub frente a nada o a copias de carpeta. Sin control de versiones, cada cambio sobrescribe el anterior y no hay forma de volver atrás ni de colaborar. Git guarda el historial localmente y GitHub lo pone en común; son el estándar de facto de la industria, así que lo que aprendes aquí lo usarás igual en tu próximo trabajo.
• marimo frente a Jupyter. Lo detallamos en la guía de marimo: en Jupyter el estado oculto y la ejecución desordenada de celdas producen cuadernos irreproducibles; marimo ejecuta como grafo reactivo y guarda el cuaderno como .py versionable.
• Librerías de datos (numpy, pandas, scikit-learn…). Aquí no hay elección: son el estándar de facto del análisis de datos y del ML en Python, con la comunidad, la documentación y el ecosistema más grandes. Todo lo que aprendas con ellas se transfiere a cualquier empleo del sector.

Si en el futuro trabajas con otras herramientas (Poetry, Conda, PyCharm, Databricks…), los conceptos son los mismos: entornos aislados, dependencias fijadas, historial de versiones y código reproducible. Cambia la herramienta, no la idea.

Instalar uv¶

uv se instala una sola vez por equipo. Elige tu sistema:

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Cierra y vuelve a abrir la terminal si el comando aún no aparece. Comprueba la instalación:

uv --version

Salida esperada: una línea como uv 0.10.4. El número depende de la versión instalada.

Si prefieres otro método, como Homebrew o winget, consulta la documentación oficial de uv. No necesitas instalar las dependencias del curso con pip.

Ruta A: preparar el repositorio del curso¶

Si todavía no tienes una copia local, clona el repositorio desde GitHub en una terminal normal. Usa la URL que te proporcione el aula:

git clone URL_DEL_REPOSITORIO
cd NOMBRE_DEL_REPOSITORIO

Si la carpeta ya está en tu equipo, omite git clone y entra directamente en ella con cd.

Desde la raíz del repositorio ejecuta:

uv sync --locked
uv run python --version
uv run marimo --version
uv run python -c "import marimo, numpy, pandas, sklearn; print('Dependencias principales disponibles')"

Qué hace cada paso:

1. uv sync --locked crea .venv si hace falta, comprueba el lockfile e instala las dependencias del proyecto sin cambiar su resolución.
2. uv run ejecuta los comandos con el Python y los paquetes del proyecto.

Salida esperada en el entorno actual del curso:

Python 3.14.3
0.23.16
Dependencias principales disponibles

El comando puede mostrar una línea Resolved ... y aun así terminar correctamente. Lo importante es que finalice con código 0; si el lockfile no corresponde con pyproject.toml, --locked detiene el proceso para que no continúes con un entorno distinto del del curso.

Ruta B: crear un proyecto desde cero¶

Usa esta ruta solo para una carpeta nueva. Abre una terminal normal y ejecuta:

mkdir mi_proyecto
cd mi_proyecto
uv init --python 3.14
uv add marimo numpy pandas matplotlib seaborn scikit-learn
uv run python -c "print('Proyecto preparado')"

uv init --python 3.14 crea la configuración inicial, establece requires-python = ">=3.14" en pyproject.toml y genera .python-version con 3.14. uv add declara las librerías, actualiza uv.lock y prepara .venv.

No hace falta ejecutar uv python pin 3.14 justo después: en este recorrido sería redundante. Ese comando sí resulta útil si el proyecto ya existe y quieres crear o cambiar .python-version sin volver a inicializarlo. Cambiar .python-version no amplía por sí solo el requisito requires-python del proyecto; si también cambia la compatibilidad soportada, revisa pyproject.toml.

Si uv no encuentra Python 3.14, instálalo y repite la operación:

uv python install 3.14

Efecto observable: aparecen o se actualizan pyproject.toml, .python-version, uv.lock y .venv; la última línea muestra Proyecto preparado. Las líneas de resolución de paquetes pueden variar.

Qué archivos se han creado¶

Esta separación evita dos errores frecuentes: creer que instalar un paquete lo declara automáticamente, o subir .venv esperando que otra persona pueda reutilizarla. Para profundizar, consulta la referencia de uv.

Comandos mínimos del día a día¶

Desde la raíz del proyecto:

uv run python --version
uv run python -c "import pandas; print(pandas.__version__)"

Salida esperada: Python pertenece a la versión del proyecto (Python 3.14.x) y se muestra una versión de pandas; en el lockfile actual del curso es 3.0.5.

No hace falta repetir uv sync cada día: uv run comprueba el entorno antes de ejecutar. Usa uv sync --locked después de clonar, de cambiar de equipo o cuando alguien haya modificado pyproject.toml o uv.lock. Tampoco hace falta activar .venv para usar uv run.

Si algo falla¶

No soluciones un ModuleNotFoundError instalando paquetes al azar en el Python global. Primero comprueba la carpeta, el intérprete y la declaración de la dependencia.

Comprobación final¶

Desde la raíz del repositorio del curso, ejecuta:

uv lock --check
uv run python -c "import marimo, numpy, pandas, sklearn; print('Entorno listo')"

Salida esperada: puede aparecer Resolved ...; después debe aparecer:

Entorno listo

Esta comprobación aporta una evidencia pequeña pero útil: la resolución es coherente y el intérprete del proyecto puede importar las dependencias principales. Las prácticas comprobarán después el comportamiento de cada ejemplo.

Siguiente paso¶

Continúa con VS Code, el editor desde el que trabajarás; después vienen los cuadernos marimo, Git y GitHub y la referencia completa de uv.