Módulo 0 — Instalación del software (antes de la S1)

Objetivo. Que llegues a la primera sesión con todo instalado y probado, de modo que el tiempo de clase se dedique al contenido y no a arreglar computadores. Sigue este tutorial completo y en orden; al final ejecutas un script que te dice si todo quedó bien.

Tiempo estimado: 30–60 minutos, según la velocidad de tu conexión (se descargan ~1.5 GB de paquetes). Hazlo con calma y con buena conexión, no la noche anterior.

Si ya tienes experiencia con Python, uv y Git, la versión corta está en ../docs/guia-entorno.md. Este documento es la versión larga, pensada para quien parte de cero o quiere entender qué está instalando y por qué.

Contenido

1. Qué vas a instalar y por qué
2. Requisitos de tu computador
3. La terminal: tu herramienta de trabajo
4. Paso 1 — Git
5. Paso 2 — uv (Python)
6. Paso 3 — Descargar el repositorio del curso
7. Paso 4 — Crear el entorno del curso
8. Paso 5 — Verificar la instalación
9. Paso 6 — Editor: VS Code o JupyterLab
10. Plan B — Google Colab
11. Herramientas que se instalan más adelante
12. Mantenimiento durante el curso
13. Preguntas frecuentes (FAQ)
14. Problemas frecuentes y su solución
15. Glosario mínimo
16. Lista de verificación final

1. Qué vas a instalar y por qué

¿Por qué un entorno virtual y no “instalar Python y ya”?

Las librerías de ML dependen unas de otras con versiones muy concretas. Si instalas todo en el Python “global” de tu máquina, tarde o temprano dos proyectos piden versiones incompatibles y se rompe alguno. Un entorno virtual es una carpeta aislada con su propio Python y sus propias librerías. El archivo ../pyproject.toml declara qué librerías necesita el curso y ../uv.lock fija la versión exacta de cada una (y de las que estas arrastran), así que todos los estudiantes y el docente trabajamos con el mismo entorno y “en mi máquina sí funciona” deja de ser un problema.

Esto es, además, el primer contenido del curso: un proyecto de ML reproducible empieza por un entorno reproducible (S1 y S2).

¿Por qué uv?

uv es un gestor de Python y de paquetes moderno, muy rápido y que resuelve en un solo programa lo que antes requería varios (instalar Python, crear el entorno, instalar librerías, fijar versiones). No necesita permisos de administrador, no toca ningún Python que ya tengas instalado y el mismo comando (uv sync) sirve para crear el entorno, actualizarlo o repararlo.

2. Requisitos de tu computador

No necesitas GPU. El curso está diseñado para correr en un portátil corriente: los datasets son pequeños y el único módulo con redes neuronales (S13) usa ejemplos que entrenan en segundos en CPU.

Si tu máquina está por debajo del mínimo, o no puedes instalar software (equipo corporativo bloqueado), ve directo al Plan B con Google Colab.

3. La terminal: tu herramienta de trabajo

Casi todo lo que sigue se hace escribiendo comandos en una terminal. No es más difícil que copiar y pegar, pero hay que abrir la terminal correcta:

Convenciones de este documento:

• Cada bloque de código es un comando: cópialo, pégalo en la terminal y pulsa Enter. Espera a que termine (vuelve a aparecer el prompt) antes de ejecutar el siguiente.
• Cuando un comando cambia según el sistema operativo, se indica explícitamente.
• Lo que va entre <...> lo reemplazas tú (por ejemplo, <tu-nombre>).
• Si un comando falla, lee el mensaje de error completo antes de buscar en §14; casi siempre dice exactamente qué pasó.

Dos comandos que usarás todo el tiempo:

cd <ruta-de-una-carpeta>

cambia a esa carpeta (“change directory”), y

dir

(en Windows) o ls (macOS/Linux) lista lo que hay en la carpeta actual.

4. Paso 1 — Git

Windows

1. Descarga el instalador desde https://git-scm.com/download/win (versión de 64 bits).
2. Ejecútalo. Puedes dejar todas las opciones por defecto; solo asegúrate de que “Git from the command line and also from 3rd-party software” esté seleccionado en la pantalla Adjusting your PATH environment.
3. Cierra y vuelve a abrir la terminal.

macOS

Abre Terminal y ejecuta:

git --version

Si no está instalado, macOS ofrece instalar las Command Line Tools; acepta y espera. Como alternativa, si usas Homebrew: brew install git.

Linux (Debian/Ubuntu)

sudo apt update && sudo apt install -y git

(En Fedora: sudo dnf install git.)

Configuración inicial (todos los sistemas)

Git firma cada cambio con tu nombre y correo. Configúralos una sola vez:

git config --global user.name "<Nombre Apellido>"

git config --global user.email "<tu-correo@utp.edu.co>"

Y evita un problema clásico de saltos de línea entre Windows y el resto del mundo:

git config --global core.autocrlf true

(en macOS/Linux usa input en vez de true).

Comprueba:

git --version

Debe responder algo como git version 2.4x.x.

Cuenta en GitHub

Crea una cuenta gratuita en https://github.com con tu correo institucional (te da acceso al GitHub Student Developer Pack). La necesitarás en la S2 para el repositorio de tu proyecto integrador; no hace falta nada más por ahora.

5. Paso 2 — uv (Python)

No instales Python por separado: uv se encarga de descargar la versión exacta que usa el curso (3.11) cuando cree el entorno, sin tocar ningún otro Python que tengas en la máquina.

Si ya tienes Anaconda o Miniconda instalados, no los desinstales ni los necesitas: uv es independiente. Solo evita instalar paquetes con conda o pip dentro del entorno del curso; siempre con uv (ver FAQ).

Windows

En PowerShell, ejecuta el instalador oficial (no requiere permisos de administrador):

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

Al terminar dice algo como everything's installed! e indica que reinicies la terminal. Cierra PowerShell y ábrela de nuevo.

Alternativa si ya usas el gestor de paquetes de Windows: winget install --id=astral-sh.uv -e.

macOS y Linux

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

Cierra la terminal y ábrela de nuevo. En macOS, si usas Homebrew, brew install uv es equivalente.

Verificación (todos los sistemas)

uv --version

Debe responder uv 0.x.x. Si dice que no reconoce el comando, ve a §14 (“uv no se reconoce”).

6. Paso 3 — Descargar el repositorio del curso

Elige dónde va a vivir el curso en tu disco. Recomendación: una carpeta sin espacios ni tildes y fuera de OneDrive, Google Drive o iCloud (los sincronizadores rompen los entornos virtuales y ralentizan Git). Por ejemplo C:\proyectos en Windows o ~/proyectos en macOS/Linux.

Créala y entra en ella:

mkdir proyectos

cd proyectos

Clona el repositorio (descarga una copia con todo su historial):

git clone https://github.com/delany-ramirez/machine_learning.git

Entra en la carpeta que se acaba de crear:

cd machine_learning

A partir de aquí, todos los comandos del tutorial se ejecutan desde esta carpeta (la raíz del repositorio). Si cierras la terminal, al volver a abrirla tendrás que hacer cd hasta aquí de nuevo.

¿Descargar el ZIP en vez de clonar? Funciona, pero pierdes lo importante: con git pull recibes las actualizaciones del material durante el curso sin volver a descargar todo. Clona.

7. Paso 4 — Crear el entorno del curso

Desde la raíz del repositorio (donde están pyproject.toml y uv.lock), un solo comando:

uv sync

uv descarga Python 3.11 (si no lo tiene ya), crea la carpeta .venv dentro del repositorio e instala en ella los ~250 paquetes del curso con las versiones exactas de uv.lock (~1.5 GB). Tarda entre 2 y 15 minutos según tu conexión; es normal que se demore en los paquetes grandes (PyTorch, MLflow). No cierres la terminal. Al final imprime Installed 2xx packages.

Cómo se usa el entorno: uv run

No hace falta “activar” nada. Anteponer uv run a cualquier comando lo ejecuta dentro del entorno del curso, desde cualquier terminal:

uv run python --version

Debe responder Python 3.11.x. Esa es la regla general del curso: uv run + lo que quieras ejecutar (uv run jupyter lab, uv run python script.py, …).

Si prefieres el estilo clásico de activar el entorno y luego escribir los comandos sin prefijo, también funciona:

.venv\Scripts\activate

en Windows, o source .venv/bin/activate en macOS/Linux. El prompt muestra (ml-curso) al inicio; deactivate lo desactiva. Ambas formas son equivalentes; en este tutorial usamos uv run porque no tiene nada que olvidar.

Por último, registra el entorno como kernel para que Jupyter y VS Code lo ofrezcan por su nombre:

uv run python -m ipykernel install --user --name ml-curso --display-name "Python (ml-curso)"

Alternativa sin uv: venv + pip

Si por alguna razón no puedes usar uv, la ruta equivalente con las herramientas que trae Python está en ../docs/guia-entorno.md. Requiere tener Python 3.11 instalado y no fija las versiones exactas, por eso uv es la opción recomendada.

8. Paso 5 — Verificar la instalación

Desde la raíz del repositorio:

uv run modulo-0-instalacion/verificar-entorno.py

El script revisa la versión de Python, que el entorno sea el .venv del repositorio, que todas las librerías del curso estén instaladas con una versión adecuada, que el kernel esté registrado y que Git y uv funcionen. Termina con un resumen como este:

============================================================
 RESUMEN: 37 OK · 0 advertencias · 0 fallos
 Entorno listo para el curso.
============================================================

Si algo falla, el propio mensaje indica qué hacer. Si no logras resolverlo con §14, envía al docente la salida completa del script (copia todo el texto, no una foto de la pantalla).

Ahora la prueba de fuego: abre JupyterLab.

uv run jupyter lab

Se abre el navegador con la interfaz de JupyterLab mostrando las carpetas del repositorio. Navega a modulo-1-fundamentos-ciclo-vida/notebooks/ y abre 01-primer-modelo-aplicado.ipynb. Arriba a la derecha debe decir Python (ml-curso); si dice otra cosa, haz clic ahí y selecciónalo. Ejecuta las dos primeras celdas con Shift + Enter. Si no hay errores, ya está.

Para cerrar JupyterLab: en la terminal donde lo lanzaste pulsa Ctrl + C (dos veces si pregunta). No basta con cerrar la pestaña del navegador.

9. Paso 6 — Editor: VS Code o JupyterLab

Puedes trabajar todo el curso solo con JupyterLab. Pero recomendamos Visual Studio Code porque integra en una sola ventana los notebooks, un editor para scripts .py, la terminal y Git, y porque es lo que vas a usar en el proyecto integrador cuando el código deje de caber en un notebook.

1. Descárgalo desde https://code.visualstudio.com e instálalo (en Windows, marca la opción Add “Open with Code” action durante la instalación; es cómoda).
2. Ábrelo y, en la barra lateral izquierda, entra en Extensiones (icono de cuadrados, o Ctrl/Cmd + Shift + X). Instala:
   • Python (de Microsoft) — trae también Pylance.
   • Jupyter (de Microsoft).
   • Opcional: Spanish Language Pack si prefieres la interfaz en español, y GitLens para ver el historial de Git dentro del editor.
3. File → Open Folder y elige la carpeta machine_learning que clonaste. Ábrela siempre desde la raíz, no desde una subcarpeta: VS Code detecta solo el .venv que está ahí, y las rutas de los notebooks lo asumen.
4. Abre cualquier .ipynb. Arriba a la derecha aparece Select Kernel: elige Python Environments → ml-curso (o .venv; es el mismo). Se recuerda para los siguientes notebooks.
5. Para la terminal integrada: Terminal → New Terminal. VS Code activa el .venv solo al abrirla (verás (ml-curso) en el prompt), así que ahí puedes escribir python … sin uv run. Si no lo hace, uv run funciona igual.

Atajos que ahorran mucho tiempo en los notebooks

10. Plan B — Google Colab

Google Colab es un Jupyter en la nube, gratuito, que solo requiere una cuenta de Google. Úsalo si:

• tu computador no cumple los requisitos o no puedes instalar software;
• estás de viaje o en un equipo prestado;
• la instalación local falla y no quieres perder la sesión mientras la resuelves.

No es el plan A porque las sesiones se desconectan tras un tiempo de inactividad, los archivos se pierden si no los guardas en Drive, y en el módulo 6 (API, Docker, MLflow) se queda corto. Pero para los módulos 1 a 5 funciona bien.

Cómo abrir un notebook del curso en Colab

1. Ve a https://colab.research.google.com → pestaña GitHub → pega https://github.com/delany-ramirez/machine_learning → Enter → elige el notebook (o usa el botón Abrir en Colab del portal del curso).
2. Al abrir un notebook en Colab, ejecuta la primera celda de código antes que nada: carga los datos del curso. Los notebooks leen datos con rutas relativas (../datos/archivo.csv), que en Colab no existen; esa primera celda (etiquetada colab-arranque) clona el repositorio, se ubica en la carpeta correcta e instala lo que Colab no trae. En tu computador esa celda no hace nada, así que puedes ejecutarla siempre.
3. Para conservar tus cambios: Archivo → Guardar una copia en Drive. Si la sesión se reinicia, vuelve a ejecutar la primera celda.

11. Herramientas que se instalan más adelante

No las instales ahora; se avisará en la sesión correspondiente.

12. Mantenimiento durante el curso

Recibir actualizaciones del material

El repositorio se actualiza antes de cada sesión. Para traer los cambios, desde la raíz del repositorio:

git pull

Si Git se queja de que tienes cambios locales en un notebook que también cambió en el repositorio, la salida más simple es guardar tu copia con otro nombre y descartar la original:

git checkout -- <ruta/del/notebook.ipynb>

y luego git pull de nuevo. Consejo: no edites los notebooks del curso directamente; duplícalos con sufijo (01-primer-modelo-aplicado-mio.ipynb) y trabaja en la copia. Ver la FAQ.

Actualizar el entorno cuando cambie pyproject.toml o uv.lock

Se avisará en clase cuando ocurra, pero no hace daño ejecutarlo después de cada git pull:

uv sync

Instala lo que falte, quita lo que sobre y no toca lo que ya está bien; si no hay cambios termina en un segundo.

Empezar de cero

Si el entorno se corrompe (paquetes que se pisan, errores extraños al importar), lo más rápido es borrarlo y recrearlo. Como los paquetes ya están en la caché de uv, tarda menos que la primera vez, y nunca afecta a tus archivos:

uv sync --reinstall

Si eso no basta, borra la carpeta .venv de la raíz del repositorio y ejecuta uv sync de nuevo.

13. Preguntas frecuentes (FAQ)

¿Puedo usar Python 3.12 o 3.13 que ya tengo instalado? No para este curso, y tampoco hace falta decidirlo: .python-version fija 3.11 porque es la versión con la que se verificó todo el material, y uv la descarga dentro del entorno sin tocar tu otro Python.

Ya tengo Anaconda / Miniconda. ¿Se estorban? No. uv no usa conda para nada. Si tu terminal muestra (base) al abrirse, ignóralo: uv run ejecuta siempre el Python del .venv del curso. Lo único que debes evitar es instalar paquetes con conda install o pip install “a pelo” dentro del entorno del curso.

¿Tengo que activar el entorno cada vez? No si usas uv run delante de cada comando (recomendado). Si prefieres activar, es en cada terminal nueva: .venv\Scripts\activate (Windows) o source .venv/bin/activate (macOS/Linux). En VS Code, la terminal integrada lo activa sola y, una vez elegido el kernel, se recuerda. En JupyterLab, elige el kernel Python (ml-curso) en cada notebook nuevo.

¿Puedo instalar paquetes adicionales? Sí, pero con uv add <paquete>, que además lo anota en pyproject.toml y uv.lock. Ten en cuenta que esos dos archivos son del repositorio del curso: git pull te avisará de un conflicto si el docente también los cambió. Por eso es mejor no instalar nada que no necesites; y para el proyecto integrador tendrás tu propio pyproject.toml.

¿Puedo trabajar en Windows con WSL? Sí, y es una buena opción si ya lo usas: sigue las instrucciones de Linux dentro de WSL. No lo instales solo por el curso; Windows nativo funciona perfectamente.

¿Sirve un Mac con chip Apple Silicon (M1/M2/M3/M4)? Sí. uv descarga automáticamente el Python y los paquetes nativos para arm64. Un Mac con procesador Intel también sirve, con una salvedad: las versiones recientes de PyTorch ya no publican paquetes para Mac Intel, así que en la S13 (redes neuronales) usa el Plan B (Colab).

¿Sirve una tableta o Chromebook? No para instalar localmente. Usa el Plan B (Colab).

¿Necesito internet durante las sesiones? Para instalar y para descargar los datasets que no están en el repositorio (los scripts descargar-*.py, se ejecutan una sola vez). El resto funciona sin conexión.

¿Cómo evito perder mi trabajo cuando el repositorio se actualiza? No edites los notebooks originales. Para cada uno que quieras modificar, haz una copia con sufijo -mio en la misma carpeta (así las rutas a ../datos/ siguen funcionando). Como esas copias no existen en el repositorio remoto, git pull nunca las tocará; solo aparecerán como “sin seguimiento” (untracked) en git status, y eso es correcto.

¿Cómo entrego un notebook? Se explica en cada ejercicio, pero la regla general es: Kernel → Restart Kernel and Run All antes de guardar, de modo que el notebook entregado se ejecute limpio de arriba abajo. Un notebook que solo funciona “si ejecutas primero la celda 14” no se considera terminado.

Mi antivirus / el proxy de la empresa bloquea las descargas. Prueba desde otra red (los datos del móvil suelen bastar para la instalación inicial). Si es un equipo corporativo con políticas, usa el Plan B.

¿Qué hago si nada de esto funciona? Escríbele al docente antes de la primera sesión con: sistema operativo, qué paso falló y el texto completo del error (copiado, no en foto). Parte de la S1 se reserva para resolver instalaciones, pero llegar con el problema identificado ahorra mucho tiempo.

14. Problemas frecuentes y su solución

15. Glosario mínimo

16. Lista de verificación final

Marca cada punto antes de la S1:

• git --version responde en la terminal.
• Git tiene configurados mi nombre y mi correo.
• Tengo cuenta en GitHub.
• uv --version responde en la terminal.
• Cloné el repositorio en una carpeta sin espacios ni tildes, fuera de OneDrive/Drive.
• uv sync terminó sin errores y uv run python --version responde Python 3.11.x.
• uv run modulo-0-instalacion/verificar-entorno.py termina con “Entorno listo para el curso”.
• Abrí 01-primer-modelo-aplicado.ipynb con el kernel Python (ml-curso) y las primeras celdas se ejecutan sin error.
• (Recomendado) VS Code instalado con las extensiones Python y Jupyter, y sabe encontrar el kernel ml-curso.
• Sé cómo traer actualizaciones del repositorio (git pull y luego uv sync).

Cuando todo esté marcado, estás listo para la Sesión 1: ../modulo-1-fundamentos-ciclo-vida/.

Versión corta de estas instrucciones: ../docs/guia-entorno.md. Programa completo del curso: ../docs/programa.md.