VS Code¶

Visual Studio Code (VS Code) es el editor que usamos en los dos módulos. En él escribirás Python, abrirás cuadernos marimo, revisarás cambios de Git y usarás la terminal para ejecutar uv, marimo y otros comandos.

VS Code no es el intérprete de Python ni el gestor de dependencias. Para evitar confusiones, piensa en cuatro piezas:

Qué aprenderás¶

Al terminar esta guía podrás:

• abrir la carpeta completa de un proyecto y reconocer su workspace;
• comprobar el intérprete que VS Code ha detectado y distinguirlo del Python global;
• preparar el entorno con uv solo cuando falten el entorno virtual o sus dependencias;
• ejecutar y depurar un script desde VS Code;
• usar la terminal, la paleta y las extensiones sin mezclar sus funciones;
• comprobar que VS Code, marimo y uv trabajan con el mismo entorno.

Instalar VS Code y las extensiones¶

Descarga Visual Studio Code desde code.visualstudio.com. Después abre la vista de extensiones (Ctrl+Shift+X en Windows/Linux; Cmd+Shift+X en macOS) e instala:

La extensión de Python puede mostrar herramientas para descubrir entornos. En este curso uv sigue siendo la fuente de verdad: añade paquetes con uv add y sincroniza con uv sync, no los instales desde una interfaz que deje el pyproject.toml sin actualizar.

Abrir un proyecto completo¶

VS Code llama workspace a la carpeta que tienes abierta. Abre la carpeta entera, no un archivo suelto: así el editor puede localizar pyproject.toml, .venv, imports, cuadernos y ajustes del proyecto.

Desde una terminal:

cd mi_proyecto
code .

Efecto observable: VS Code abre mi_proyecto como carpeta raíz y el nombre del proyecto aparece en el explorador. Si code no está disponible, usa Archivo -> Abrir carpeta. En macOS puedes instalar el comando desde la paleta con Shell Command: Install 'code' command in PATH.

Una vez abierta la carpeta, crea una terminal nueva desde Terminal -> Nueva terminal. Comprueba que estás en el lugar correcto:

pwd
ls pyproject.toml

En Windows PowerShell, usa Get-ChildItem pyproject.toml para la segunda línea. Si el archivo no aparece, corrige la carpeta antes de ejecutar comandos del proyecto.

Preparar el intérprete del proyecto¶

No siempre necesitas ejecutar uv sync. Un proyecto nuevo creado con uv init y uv add puede tener ya creado .venv, el lockfile y sus dependencias. En ese caso, comprueba el entorno y continúa. Usa esta tabla para decidir:

Si trabajas con el repositorio del curso y el entorno falta o está incompleto, el comando reproducible es:

uv sync --locked

uv sync sincroniza el entorno virtual .venv con las dependencias declaradas en pyproject.toml. Si hace falta, crea .venv, resuelve versiones e instala los paquetes. Por eso se utiliza cuando el entorno o sus dependencias faltan o han cambiado; no es una orden que tengas que repetir antes de cada ejecución.

El parámetro --locked cambia esa decisión: exige que exista uv.lock y que coincida con pyproject.toml. Instala la resolución ya registrada y falla si necesita modificarla. Así evita que un repositorio clonado termine usando versiones distintas sin que se revise el cambio. Para un proyecto nuevo que aún no tiene uv.lock, no uses --locked: ejecuta primero uv sync o, normalmente, uv add, que crea y actualiza el lockfile.

Después comprueba el entorno:

uv run python --version
uv run marimo --version

Salida esperada en el entorno actual del curso:

Python 3.14.3
0.23.16

Las versiones concretas dependen del lockfile. La primera línea se obtiene con el intérprete del proyecto y la segunda con el marimo declarado en él.

Una vez preparado el entorno, la extensión de Python suele detectar automáticamente el entorno virtual .venv. Comprueba el intérprete que aparece en la barra de estado o en la paleta de Python. Si muestra el .venv del proyecto, no necesitas ejecutar ninguna acción adicional.

La selección manual es opcional y solo hace falta si VS Code no detecta el entorno o muestra otro Python. En ese caso, abre la paleta (Ctrl+Shift+P en Windows/Linux; Cmd+Shift+P en macOS), ejecuta Python: Select Interpreter y elige el entorno virtual del proyecto:

• Linux y macOS: .venv/bin/python;
• Windows: .venv\Scripts\python.exe.

El intérprete que usa VS Code aparece en la barra de estado. Si .venv no aparece, comprueba que has abierto la carpeta raíz y que el entorno está preparado. Si faltan el entorno o las dependencias, ejecuta uv sync --locked cuando exista uv.lock o uv sync si todavía no existe; después recarga la ventana o selecciona manualmente el entorno.

La terminal integrada¶

La terminal integrada es una terminal normal situada dentro de VS Code. Es el lugar recomendado para comandos de proyecto. No repitas uv sync en cada sesión; úsalo después de clonar, cambiar dependencias o detectar que falta el entorno:

uv run python script.py
git status

Para scripts y herramientas, prefiere uv run: evita ejecutar el archivo con un Python distinto del que Pylance está analizando. Activar .venv puede ser cómodo para una sesión, pero no sustituye a declarar dependencias con uv.

Si cambias el intérprete mientras ya hay una terminal abierta, la terminal puede conservar el PATH anterior. Cierra esa terminal y crea otra antes de diagnosticar un ModuleNotFoundError.

La paleta de comandos¶

Ctrl+Shift+P (Cmd+Shift+P en macOS) abre la paleta. Escribe una acción en vez de buscarla por los menús:

Los nombres pueden aparecer en inglés aunque el idioma de VS Code esté en español. Buscar Python o marimo suele encontrar la acción correcta.

Editar, ejecutar y depurar Python¶

Crea un archivo ejemplo.py con este contenido:

def doble(numero):
    return numero * 2


print(doble(21))

Para ejecutar, pulsa el botón de reproducción del editor o usa Python: Run Python File in Terminal.

Salida esperada:

42

Depurar significa ejecutar el programa pausándolo en los puntos que elijas, para observar cuánto valen las variables en ese momento. Para depurar:

1. Haz clic en el margen izquierdo junto a return numero * 2 para crear un punto de interrupción (aparece un punto rojo).
2. Pulsa F5 o elige Run and Debug. Si VS Code pregunta qué configuración usar, elige Python Debugger y después Python File.
3. Cuando la ejecución se detenga, observa numero en Variables o en la consola de depuración.
4. Usa continuar, paso siguiente y detener para recorrer el programa.

Un punto de interrupción no cambia el código: pausa la ejecución para observar su estado. Si el botón ejecuta otro archivo o aparece otro Python, comprueba el workspace y el intérprete seleccionado; para una prueba independiente usa uv run python ejemplo.py.

Ajustes del editor¶

VS Code distingue dos niveles de configuración:

• Usuario: se aplica a todos tus proyectos y se abre con Preferences: Open User Settings (JSON).
• Workspace: solo afecta a la carpeta abierta y se guarda en .vscode/settings.json; se puede compartir si no contiene rutas personales ni secretos.

La configuración del workspace gana cuando entra en conflicto con la del usuario. Un ajuste útil para guardar automáticamente con un pequeño retardo es:

{
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000
}

Actívalo desde Archivo -> Autoguardado o desde los ajustes. El idioma, el tema y el tamaño de letra son preferencias personales; no es necesario versionarlos para que el proyecto funcione. Para previsualizar Markdown usa Ctrl+Shift+V (Cmd+Shift+V en macOS).

Extensiones y herramientas del proyecto¶

Una extensión mejora la experiencia del editor, pero no siempre forma parte del entorno reproducible. Por ejemplo, la extensión de Ruff puede mostrar diagnósticos aunque ruff no esté en pyproject.toml. Si todo el equipo debe usarlo, o si se ejecuta en comprobaciones automáticas, decláralo y ejecútalo con uv:

uv add --dev ruff
uv run ruff check .

Del mismo modo, abrir un cuaderno requiere la extensión de marimo, pero sus dependencias Python se gestionan con uv. Consulta Cuadernos marimo para el flujo de celdas y kernels, y Git y GitHub para la vista de control de código fuente.

Source Control desde VS Code¶

La vista Source Control ofrece el flujo visual de Git:

1. Revisa los archivos modificados en Changes.
2. Pulsa + para preparar un archivo o elige preparar todos.
3. Revisa el diff preparado.
4. Escribe el mensaje y pulsa Commit.
5. Usa Sync Changes para traer y publicar cambios cuando la rama esté configurada.

Es el mismo ciclo que git status, git add, git commit, git pull y git push. Si una acción visual no está clara, abre la terminal y comprueba el estado con los comandos de Git y GitHub.

Problemas habituales¶

Comprobación final¶

Desde la terminal integrada y con la carpeta del proyecto abierta, ejecuta:

uv run python -c "import sys; print(sys.executable)"
uv run python -c "import pandas; print(pandas.__version__)"
git status --short

Salida esperada: la ruta del ejecutable contiene .venv, se muestra una versión de pandas y Git devuelve el estado de la carpeta sin errores. En el proyecto actual el ejecutable está en .venv/bin/python y pandas es 3.0.5; la ruta y la versión pueden variar según el sistema y el lockfile.

Siguiente paso¶

Sigue con los cuadernos marimo.