Ambientes virtuales en Python: buenas prácticas para desarrollo de software de investigación

RS-Latam 2026

Autor/a

Stephanie Orellana Bello

Fecha de publicación

25 de agosto de 2026

1 Un poco de Contexto

1.1 Reproducibilidad

La reproducibilidad tiene diferentes capas, hoy aprenderemos solo de una parte.

Ziemann, M., Poulain, P., & Bora, A. (2023). The five pillars of computational reproducibility: Bioinformatics and beyond. Briefings in Bioinformatics, 24(6), bbad375. https://doi.org/10.1093/bib/bbad375

1.2 ¿Por qué hablamos de ambientes?

En RSE, nuestro código no vive aislado.

Para ejecutar un proyecto necesitamos, entre otras cosas:

  • una versión de Python;
  • paquetes y dependencias;
  • versiones compatibles;
  • un ambiente donde instalar esas dependencias.

¿Qué necesitas además de main.py para ejecutar un proyecto de otra persona?

1.3 Python

Versión de Python

Pueden haber múltiples instaladas en el sistema

Ambiente Virtual

Creamos un espacio aislado para instalar los paquetes que requiere nuestro proyecto

Paquetes

Instalamos las librerías (y sus dependencias) necesarias para que nuestro código funcione


Esto garantiza una capa mínima de reproducibilidad, pero no resuelve:

  • Mala organización del proyecto
  • Falta de documentación
  • Mal diseño de dependencias
  • Diferentes sistemas operativos

1.3.1 Versión de Python

Un proyecto puede requerir una versión específica de Python.

Por ejemplo:

Python 3.11
Python 3.12
Python 3.13

Puedes consultar la versión que estás utilizando con:

python --version

1.3.2 Paquetes

Python incluye una biblioteca estándar, pero muchos proyectos necesitan paquetes externos.

Por ejemplo:

import pandas
import seaborn

Estos paquetes deben estar instalados en el ambiente donde ejecutamos nuestro proyecto.

1.3.3 Ambiente virtual

Un ambiente virtual permite mantener aisladas las dependencias de un proyecto.

El caso de pandas. En enero de este año se lanzó la versión 3.0 de pandas que incluye una serie de cambios que hacen que ciertos códigos hechos con versiones anteriores ya no sean compatibles.

Acá es donde tener ambientes separados para nuestros proyectos resulta crucial:

proyecto A
└── ambiente A
    └── pandas 2.x

proyecto B
└── ambiente B
    └── pandas 3.x

Así, cambiar las dependencias de un proyecto no debería romper otro.

1.4 Muchas Herramientas

Fuente: Anna-Lena Popkes

2 ¿Qué haremos hoy?

Un pequeño proyecto de Python que:

  1. lee datos de temperatura desde un CSV disponible en GitHub
  2. usa pandas para trabajar con los datos
  3. usa seaborn para visualizar una serie temporal
  4. usa scipy para calcular la tendencia

Esto es algo muy simple porque el foco del taller no es aprender a programar en Python.

Acá aprenderemos a:

Crear un ambiente virtual con venv e instalar los paquetes necesarios con pip

Hacer lo mismo (y más) con uv

3 Preparar el computador

3.1 Python

Necesitamos una instalación funcional de Python.

Comprueba:

python --version

En algunos sistemas puede ser:

python3 --version

3.1.1 Windows

Descarga Python desde la página oficial:

https://www.python.org/downloads/windows/

Durante la instalación, recuerda activar la opción para agregar Python al PATH.

Si al ejecutar algún script en powershell recibes el mensaje:

la ejecución de scripts está deshabilitada en este sistema. Para obtener más información, consulta el tema about_Execution_Policies en https:/go.microsoft.com/fwlink/?LinkID=135170.

ejecuta en powershell

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

3.1.2 macOS

Puedes instalar Python desde:

https://www.python.org/downloads/macos/

Si utilizas Homebrew:

brew install python

3.1.3 Linux

Consulta las instrucciones oficiales para tu distribución:

https://www.python.org/downloads/

En Ubuntu/Debian, por ejemplo:

sudo apt update
sudo apt install python3 python3-venv python3-pip
Nota

Si ya tienes Python instalado y python --version funciona, no necesitas instalarlo nuevamente.

4 Forma nativa: venv + pip

4.1 Crear una carpeta para trabajar

Crearemos una carpeta de la manera usual según tu sistema operativo y la abriremos en el IDE que tengan instalado.

Yo estaré trabajando con Positron y VSCode

4.2 Crear el ambiente

Ejecuta en la terminal:

python -m venv .venv

Esto crea una carpeta .venv con el ambiente virtual.

4.3 Activar el ambiente

El ambiente debe activarse para ser usado, la manera de activarlo varía según el sistema operativo que utilizamos.

4.3.1 macOS / Linux

En la terminal

source .venv/bin/activate

4.3.2 Windows PowerShell

.venv\Scripts\Activate.ps1

4.3.3 Windows CMD

.venv\Scripts\activate.bat

Cuando el ambiente está activo, normalmente verás (.venv) al comienzo de la línea de comandos.

4.4 Comprobar el Python utilizado

En la terminal

python --version

4.5 Crea el archivo de código de ejemplo

Crearemos un nuevo archivo llamado main.py con el siguiente contenido:

import pandas as pd
import seaborn as sns
import matplotlib.pyplot as plt

# Leer datos desde GitHub
url = "https://raw.githubusercontent.com/datasets/global-temp/main/data/annual.csv"

df = pd.read_csv(url)

# Filtrar datos de GISTEMP
df = df[df["Source"] == "GISTEMP"]

# Graficar anomalía de temperatura global
sns.lineplot(data=df, x="Year", y="Mean")

plt.title("Anomalía de temperatura global")
plt.xlabel("Año")
plt.ylabel("Anomalía de temperatura (°C)")
plt.show()

4.6 Instalar paquetes

Ahora instalaremos las dependencias del ejemplo:

pip install pandas seaborn

Puedes revisar qué quedó instalado:

pip list

Quiero incluir una línea de tendencia en mi gráfico, así que modifico el código:

import pandas as pd
import seaborn as sns
import matplotlib.pyplot as plt
from scipy.stats import linregress

url = "https://raw.githubusercontent.com/datasets/global-temp/main/data/annual.csv"

df = pd.read_csv(url)
df = df[df["Source"] == "GISTEMP"]

# Calcular regresión lineal
result = linregress(df["Year"], df["Mean"])

# Línea de tendencia
df["Trend"] = result.intercept + result.slope * df["Year"]

# Graficar
sns.lineplot(data=df, x="Year", y="Mean", label="Temperatura")
sns.lineplot(data=df, x="Year", y="Trend", label="Tendencia")

# Ecuación
equation = f"y = {result.slope:.4f}x + {result.intercept:.2f}"

plt.text(
    0.05,
    0.95,
    equation,
    transform=plt.gca().transAxes,
    verticalalignment="top"
)

plt.title("Anomalía de temperatura global")
plt.xlabel("Año")
plt.ylabel("Anomalía de temperatura (°C)")
plt.tight_layout()
plt.show()

Y debo instalar el nuevo paquete

pip install scipy

4.7 Guardar las dependencias

Una forma tradicional de registrar las dependencias es:

pip freeze > requirements.txt

Esto genera:

requirements.txt

Puedes abrirlo y revisar las versiones instaladas.

4.8 Ejecutar el ejemplo

Ejecuta:

python main.py

5 Forma con: uv

uv es una herramienta moderna para gestionar proyectos, ambientes, versiones de Python y dependencias.

Documentación oficial:

https://docs.astral.sh/uv/

Una captura de pantalla sobre lo que promete:

5.1 Instalar uv

5.1.1 macOS y Linux

La instalación oficial ofrece un instalador independiente:

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

También puedes utilizar Homebrew en macOS:

brew install uv

5.1.2 Windows

En PowerShell:

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

También puedes instalarlo mediante WinGet:

winget install --id=astral-sh.uv -e
Nota

Después de instalar uv, abre una nueva terminal si el instalador te indica que debes actualizar el PATH.

Comprueba la instalación:

uv --version

5.2 Crear el proyecto con uv

5.2.1 Proyecto por defecto

Primero exploraremos un proyecto de uv que se crea con las configuraciones por defecto. Es una buena forma de entender cómo estructurar nuestros proyectos de python más complejos.

Haremos una nueva carpeta para trabajar y la abriremos en nuestro IDE.

Puedes crear un proyecto nuevo desde la terminal con:

uv init

Esto crea la estructura básica del proyecto como tipo “aplicación empaquetada”

mi-proyecto/
├── .python-version   ← versión de Python
├── .venv/            ← ambiente virtual
├── README.md         ← documentación
├── pyproject.toml    ← configuración y dependencias
├── uv.lock           ← versiones concretas de las dependencias
└── src/              ← código fuente
    └── mi_proyecto/
        └── __init__.py

Este tipo de estructura inicial es muy útil para comenzar nuestros proyectos de manera ordenada y con los archivos mínimos para garantizar su reproducibilidad.

Acá dejo un recordatorio de qué significa cada cosa en el `pyproject.toml``

[project]

name = "proyecto-uv0"             # ¿Cómo se llama?
version = "0.1.0"                 # ¿Qué versión?
description = "..."               # ¿Qué hace?
readme = "README.md"              # ¿Dónde está la documentación?
authors = [...]                   # ¿Quién lo desarrolla?
requires-python = ">=3.13"       # ¿Qué Python necesita?
dependencies = [...]              # ¿Qué paquetes necesita?

[project.scripts]
proyecto-uv0 = "proyecto_uv0:main" # ¿Cómo lo ejecuto?

[build-system]
...                                # ¿Cómo se construye?

5.2.2 Proyecto forma simple

Haremos una nueva carpeta y la abriremos en nuestro IDE. Ahora utilizaremos algunas opciones de uv init para adecuar la estructura a nuestro código simple

uv init --no-package --python 3.13

Acá le decimos que queremos una aplicación simple “no empaquetada” y que use la versión 3.13 de python

5.2.2.1 Agregar dependencias

En lugar de instalar los paquetes directamente con pip como en el ejemplo anterior con uv podemos declarar las dependencias del proyecto:

uv add pandas seaborn

uv crea o actualiza:

pyproject.toml
uv.lock
.venv

Mirar el arbol de dependencias:

uv tree

5.2.2.2 Ejecutar el proyecto

Con uv puedes ejecutar el programa mediante:

uv run python main.py

Esto es todo, uv se encargua de utilizar el ambiente y las dependencias correspondientes.

6 Pasar de un método a otro

venv + pip uv
Ambiente virtual venv uv venv
Activar ambiente source .venv/bin/activate (macOS/Linux) .\.venv\Scripts\activate (Windows) No es necesario
Instalar paquetes pip install uv add
Declarar dependencias requirements.txt o pyproject.toml pyproject.toml
Versiones bloqueadas requirements.txt uv.lock
Gestionar Python No, solo ejecutables instalados Sí
Ejecutar proyecto Activar .venv y python main.py uv run

6.1 Si alguien que usa uv quiere reconstruir un ambiente hecho con venv+pip

uv venv
uv pip install -r requirements.txt

6.2 Si alguien que no usa uv quiere colaborar en un proyecto uv

python -m venv .venv # usar la versión de python especificada en toml, si no no funciona
soruce .venv/bin/activate # en mac/Linux, en windows .\.venv\Scripts\activate
pip install . # lee desde toml

6.3 Si alguien usa uv quiere colaborar

uv sync

7 Ideas finales

  1. La versión de Python y los paquetes son cosas diferentes
  2. Un ambiente virtual aísla las dependencias de un proyecto
  3. venv crea el ambiente y pip instala paquetes
  4. pyproject.toml permite declarar requisitos del proyecto, no es algo propio de uv sino que es un estándar de Python
  5. uv integra la gestión de Python, ambientes y dependencias
  6. uv.lock ayuda a reproducir las versiones resueltas
  7. Ninguna de estas herramientas, por sí sola, reproduce completamente el sistema operativo
  8. Ninguna de estas herramientas, por sí sola, hace que nuestro proyecto sea 100% reproducible, esto es solo una capa

Si tienes dudas o comentarios: sporella.dev@gmail.com