Módulos e imports en Python: import, from-import, pip y paquetes

Un archivo es un módulo

Cuando tu código Python crece más allá de un solo script, vas a querer partirlo en varios archivos. El sistema de módulos de Python es simple: cualquier archivo .py es automáticamente un módulo, importable por nombre.

Imagina que tienes un archivo util.py:

# util.py
def greet(name):
    return f"Hello, {name}"

PI = 3.14159

Desde otro archivo en el mismo directorio — main.py — puedes usarlo:

# main.py
import util

print(util.greet("Ada"))
print(util.PI)

Ejecuta python3 main.py y Python encuentra util.py, lo ejecuta una vez, y expone todo lo definido en el nivel superior (funciones, variables, clases) como atributos del módulo util.

Las tres formas de import

Importar el módulo entero. Accedes a las cosas de dentro a través del nombre del módulo:

Importar nombres específicos. Se vuelven directamente disponibles:

Importar con un alias. Útil cuando el nombre del módulo es largo o cuando dos módulos comparten nombre:

import numpy as np
import pandas as pd

# Ahora usa np.array(...), pd.DataFrame(...), etc.

Hay una cuarta forma, from math import *, que saca todo a tu namespace. Evítala fuera de experimentación en REPL — hace imposible saber de dónde viene un nombre y crea colisiones silenciosas de nombres.

Cuándo se ejecutan los imports

Python ejecuta el código de nivel superior de un módulo importado una vez, la primera vez que se importa en un programa dado. Los imports posteriores del mismo módulo devuelven la versión ya cargada. Así que esto:

# setup.py
print("setup module loading...")
VALUE = 42

# main.py
import setup
import setup  # importado dos veces — pero "loading" solo se imprime una
print(setup.VALUE)

Solo imprime "setup module loading..." una vez. Esto importa: si pones efectos secundarios (como abrir un archivo o imprimir) en el nivel superior del módulo, pasan en tiempo de import, que normalmente no es lo que quieres. Ponlos dentro de funciones.

La librería estándar

Python viene con una gran librería estándar de módulos. Ya has visto unos cuantos. Algunos a los que recurrirás constantemente:

• math — sqrt, sin, log, constantes como pi y e.
• random — números aleatorios, elecciones, barajar.
• datetime — fechas y horas.
• json — leer/escribir JSON.
• os, os.path — rutas y operaciones del sistema de archivos.
• pathlib — manejo moderno de rutas, a menudo más agradable que os.path.
• re — expresiones regulares.
• collections — tipos de colección especializados (Counter, defaultdict, deque, etc.).
• itertools, functools — helpers de iteradores y funciones.
• csv — leer y escribir archivos CSV.

La librería estándar ya está instalada — nada que instalar con pip.

Paquetes de terceros y pip

Para cualquier cosa que la librería estándar no cubra, el Python Package Index (PyPI) aloja cientos de miles de paquetes. Instálalos con pip:

pip install requests
pip install pandas
pip install --upgrade requests
pip uninstall requests

Una vez instalados, se importan como cualquier otra cosa:

import requests

response = requests.get("https://api.example.com/data")
print(response.status_code)

Unos cuantos consejos para gestionar esto con cordura:

Usa entornos virtuales

Instalar todo globalmente lleva al dolor. Proyectos distintos necesitan versiones distintas; algunos paquetes dependen de versiones específicas de Python; las instalaciones globales requieren derechos de admin en algunos sistemas. Un entorno virtual es una instalación aislada de Python solo para un proyecto:

python3 -m venv .venv
source .venv/bin/activate    # macOS/Linux
.venv\Scripts\activate       # Windows

pip install requests

Mientras el venv esté activado, pip instala en la carpeta del proyecto, no en tu sistema. Desactiva con deactivate cuando hayas terminado.

Fija tus dependencias

Guarda la lista de paquetes instalados para que otros (incluido tu yo futuro) puedan recrear el mismo entorno:

pip freeze > requirements.txt

Luego más adelante:

pip install -r requirements.txt

Herramientas como Poetry, pipenv y uv manejan esto más ergonómicamente, pero el flujo plano de pip + requirements.txt sigue estando bien para aprender.

Escribir tus propios módulos

Cuando tienes funciones que quieres reutilizar entre archivos, ponlas en su propio módulo. Convenciones de nombrado:

• Los nombres de archivo deberían ser lower_snake_case.py.
• Las funciones y variables a nivel de módulo también lower_snake_case.
• Las clases usan PascalCase.

# shopping.py
PRICES = {"apple": 0.50, "bread": 2.00}

def total(items):
    return sum(PRICES[item] for item in items)

# main.py
from shopping import total, PRICES

print(total(["apple", "bread"]))
print(PRICES)

Si dos archivos en la misma carpeta se importan el uno al otro, puedes crear accidentalmente un import circular. El arreglo habitual es mover el código compartido a un tercer archivo que ambos importen.

Paquetes: carpetas de módulos

Cuando tengas más de un puñado de módulos, agrúpalos en un paquete — una carpeta con un archivo __init__.py dentro:

myproject/
├── main.py
└── utils/
    ├── __init__.py
    ├── text.py
    └── numbers.py

Entonces:

from utils.text import slugify
from utils import numbers

print(slugify("Hello, World"))
print(numbers.mean([1, 2, 3]))

El __init__.py puede estar vacío; su presencia es lo que hace que utils sea un paquete. Python moderno también soporta "namespace packages" sin __init__.py, pero para empezar, la versión explícita es más clara.

Una pequeña checklist cuando los imports se rompen

• "ModuleNotFoundError: No module named X". O el paquete no está instalado, o estás ejecutando Python desde un intérprete distinto al que usaste para pip install. En un venv, asegúrate de que el venv esté activado.
• "ImportError: cannot import name Y from X". El módulo existe, pero el nombre que pediste no está ahí. Comprueba typos y mira el contenido real del módulo.
• "Circular import". Dos módulos se importan el uno al otro. Mueve el código compartido a un tercer módulo.

Siguiente: instalar paquetes de terceros

Tus propios módulos te llevan lejos, pero la mayoría de proyectos reales también tiran de librerías de PyPI — requests, pandas, un framework de tests. La siguiente página cubre pip, cómo instalar paquetes limpiamente y cómo registrar de qué depende tu proyecto.