Skip to main content

Creando un proyecto Python con uv

⏱ Dedicación recomendada: 0 minutos
Esto considera el contenido visible y relevante, e ignora texto colapsado o marcado como opcional.

r8vnhill/echo-app-py-uv

Esta lección te guiará paso a paso en la creación de un proyecto moderno en Python utilizando uv, una herramienta ultrarrápida para entornos virtuales y gestión de dependencias.

A través de este recorrido, aprenderás a:

  • Instalar Python y uv.
  • Crear una estructura de proyecto clara y extensible.
  • Configurar tu primer pyproject.toml.
  • Ejecutar un Hello, World! en un entorno virtual aislado.

El objetivo no es solo que el proyecto funcione, sino que quede bien organizado desde el comienzo —pensando en mantenerlo, extenderlo y escalarlo más adelante durante el curso.

Prepárate para pasar de simples scripts a proyectos Python bien estructurados. ¡Comencemos!

🐍 Paso -1: Instalar Python​

Antes de comenzar a trabajar con uv, necesitamos asegurarnos de tener Python instalado.

Python es un lenguaje de programación interpretado, de propósito general, conocido por su sintaxis clara, su amplia comunidad y su gran ecosistema de herramientas. Se utiliza en una amplia gama de áreas: desarrollo web, scripting, análisis de datos, inteligencia artificial y automatización, entre otros.

En esta guía, usaremos Python como plataforma base para crear un proyecto estructurado y moderno, similar a cómo se hace en otros ecosistemas con herramientas como Gradle en Kotlin.

Puedes descargar Python desde python.org, o instalarlo con un gestor de paquetes según tu sistema operativo:

En PowerShell
scoop install python

✅ Verificar la instalación de Python​

Una vez instalado, puedes verificar que esté correctamente disponible ejecutando:

En PowerShell
py --version
Salida esperada (puede variar)
Python 3.13.2

La salida debe mostrar una versión de Python igual o superior a 3.8. No es necesario que coincida exactamente con la que aparece aquí (3.13.2), pero sí debe confirmar que Python está instalado y disponible desde la terminal.

⚙️ Paso 0: Instalar uv​

uv es una herramienta ultrarrápida para gestionar entornos virtuales e instalar dependencias en proyectos basados en pyproject.toml. Aunque todavía no ha alcanzado su versión 1.0, se encuentra en una etapa muy activa de desarrollo y ya ofrece funcionalidades equivalentes —e incluso superiores en algunos aspectos— a herramientas como PDM, Poetry o Hatch.

¿Por qué usamos uv?

Elegimos uv porque, a diferencia de otras alternativas, soporta de forma nativa estructuras multi-módulo (workspaces o monorepos). Esto lo hace ideal no solo para proyectos como este —donde separamos una biblioteca (core) y una aplicación (app) dentro del mismo repositorio—, sino también para el enfoque que adoptaremos durante el curso: mantener una clara separación entre la lógica de negocios y la lógica de aplicación.

Gracias a esta capacidad, podremos organizar nuestros proyectos de forma modular, escalar su complejidad de manera controlada y facilitar la reutilización de componentes.

Instálala según tu sistema operativo:

En PowerShell
scoop install main/uv

✅ Verificar la instalación de uv​

Una vez instalada, verifica que esté correctamente disponible con:

uv --version
Salida esperada (puede variar)
uv 0.6.14 (a4cec56dc 2025-04-09)

Aunque la versión puede variar, deberías ver un número como 0.x.x seguido de un identificador de compilación.
Eso confirma que uv está correctamente instalado y listo para usarse en la gestión del proyecto.

🧱 Paso 1: Crear el directorio del proyecto​

Vamos a crear una carpeta raíz llamada echo-app-py-uv, donde ubicaremos los distintos módulos del proyecto.

En PowerShell
'echo-app-py-uv' | ForEach-Object {
    New-Item -Path $_ -ItemType Directory -Force | Out-Null
    Set-Location -Path $_
}
¿Qué acabamos de hacer?

Este bloque crea una carpeta llamada echo-app-py-uv (si aún no existe) y cambia el directorio actual a esa carpeta.

  • New-Item -ItemType Directory -Force crea el directorio, incluso si ya existe.
  • Set-Location cambia el directorio de trabajo actual.
  • Out-Null evita que la terminal imprima mensajes innecesarios.

Es una forma clara y robusta de inicializar el entorno antes de estructurar el proyecto.

⚙️ Paso 2: Inicializar el proyecto con uv​

Inicializa la estructura base del proyecto ejecutando el siguiente comando desde la carpeta raíz:

En tu terminal
uv init

Este comando genera una estructura mínima compatible con uv, incluyendo archivos esenciales para la configuración del entorno.

🗂️ Resultado esperado​

Explicación de la estructura

Al ejecutar uv init, se crea un archivo pyproject.toml con la configuración mínima del proyecto, así como un archivo main.py vacío y otros archivos útiles como .gitignore y .python-version.

Esta estructura proporciona una base lista para agregar dependencias, definir entornos y comenzar a organizar tus módulos (core/, app/, etc.) en los siguientes pasos.

🧩 Revisar el archivo pyproject.toml​

Después de ejecutar uv init, se habrá generado un archivo pyproject.toml con la configuración mínima del proyecto. Antes de continuar, es importante revisarlo y ajustar los campos principales según tus necesidades.

Asegúrate de que el contenido sea similar a lo siguiente:

pyproject.toml
[project]
name = "echo-app-py-uv"
version = "0.1.0"
description = "Proyecto base con uv"
readme = "README.md"
requires-python = ">=3.10"
dependencies = []
¿Qué acabamos de hacer?

Este archivo define los metadatos esenciales del proyecto y servirá como punto de partida para declarar dependencias, entornos, y más adelante, submódulos.

  • name: el nombre del proyecto.
  • version: la versión actual del proyecto.
  • description: una breve descripción (puedes completarla más adelante).
  • readme: archivo que se usará como documentación principal del proyecto.
  • requires-python: versión mínima de Python requerida.
  • dependencies: se dejará vacío por ahora, pero aquí podrás agregar bibliotecas necesarias en pasos posteriores.

No es necesario declarar aún ningún workspace, ya que por ahora el proyecto será de un solo módulo.

🎸 Paso 3: Primer Hello World​

Vamos a editar el archivo main.py generado por uv init para imprimir un mensaje especial inspirado en Foo Fighters. Será nuestra primera verificación de que el entorno está funcionando y que podemos ejecutar código en Python con éxito.

main.py
def main():
    print("It's times like these you learn to code again.")


if __name__ == "__main__":
    main()
¿Qué acabamos de hacer?

Este archivo define una función main() que imprime un mensaje en consola —una versión personalizada del clásico Hello, World!.

  • def main(): Define la función principal de nuestro programa.
  • print(...): Muestra un mensaje en pantalla.
  • if __name__ == "__main__": Asegura que la función main() solo se ejecute si el archivo se ejecuta directamente (no si es importado desde otro módulo).

Este patrón es una convención común en Python, especialmente útil para mantener el código organizado y reutilizable cuando el proyecto crezca.

▶️ Ejecutar el proyecto​

Una vez que hayas modificado main.py, puedes ejecutar tu programa directamente con:

En PowerShell
uv venv && `
.\.venv\Scripts\activate && `
py main.py
¿Qué acabamos de hacer?

Este bloque ejecuta tu programa en un entorno virtual recién creado con uv:

  • uv venv: Crea un entorno virtual dentro de la carpeta .venv si aún no existe.
  • .venv\Scripts\activate: Activa el entorno virtual en PowerShell, aislando las dependencias del sistema.
  • py main.py: Ejecuta el archivo principal del proyecto utilizando el intérprete de Python.

✅ Este es un patrón estándar para trabajar de forma segura y reproducible en proyectos Python con uv.

¿Cómo salgo del entorno virtual?

Para salir del entorno virtual, simplemente ejecuta el siguiente comando en cualquier terminal:

En tu terminal
deactivate
Opción más corta con uv run

Para ejecutar tu programa de manera más sencilla, puedes usar el siguiente comando:

En tu terminal
uv run main.py

Esto es equivalente a crear y activar el entorno virtual manualmente, pero lo hace automáticamente por ti. Pero de todos modos enseñamos la forma "manual" para que entiendas lo que está sucediendo detrás de escena 😄

🎯 Conclusiones​

En esta lección diste tus primeros pasos hacia un flujo de trabajo moderno en Python. Aprendiste a instalar Python y uv, crear un proyecto con estructura clara, ejecutar código dentro de un entorno virtual y comprender el rol de pyproject.toml como archivo central de configuración.

Estos fundamentos te preparan para construir proyectos más complejos y modulares en el futuro.

🔑 Puntos clave​

  • Python es un lenguaje versátil, ideal para desarrollo rápido y estructurado.
  • uv permite inicializar proyectos, gestionar entornos virtuales y declarar dependencias desde pyproject.toml.
  • uv init crea una base lista para empezar.
  • El patrón if __name__ == "__main__" establece un punto de entrada reutilizable.
  • Ejecutar código dentro de entornos virtuales promueve aislamiento y reproducibilidad.

🧰 ¿Qué nos llevamos?​

Aunque el proyecto es simple, sentamos las bases para avanzar hacia una organización modular, reproducible y mantenible.

A partir de aquí, estarás listx para:

  • Agregar nuevos módulos y responsabilidades.
  • Gestionar dependencias de forma declarativa.
  • Integrar pruebas, tareas automatizadas y publicación de paquetes.

Esta transición —de scripts sueltos a proyectos estructurados— es clave para desarrollar software sostenible y profesional.

📖 Referencias​

🔥 Recomendadas​

  • 🌐 "Working on projects" de la documentación oficial de uv: Explica cómo iniciar y estructurar un proyecto Python moderno con uv, incluyendo la creación automática de archivos como pyproject.toml, main.py y .python-version, así como el uso del entorno virtual .venv y el archivo uv.lock. Además, enseña cómo añadir y eliminar dependencias, ejecutar scripts en entornos controlados, y construir distribuciones del proyecto. Es especialmente relevante para esta lección porque complementa el uso básico de uv init y uv run, brindando una visión completa del flujo de trabajo profesional que iremos construyendo a lo largo del curso.