Módulo os en Python: archivos, carpetas y entorno

El módulo os en Python permite interactuar con el sistema operativo desde un script. Con él puedes consultar la carpeta actual, crear directorios, listar archivos, renombrar elementos, leer variables de entorno y combinar rutas de forma compatible con Windows, macOS y Linux.

Aunque pathlib ofrece una interfaz más moderna para muchas tareas de archivos, os sigue siendo fundamental porque incluye operaciones de entorno, procesos, permisos y compatibilidad con APIs tradicionales.

Importar el módulo os

import os

print(os.name)

os.name suele devolver nt en Windows y posix en Linux o macOS. No conviene basar toda la lógica del programa en este valor; normalmente es mejor utilizar funciones portables.

La documentación oficial del módulo os reúne las funciones disponibles en cada sistema.

Consultar y cambiar la carpeta actual

import os

current = os.getcwd()
print(current)

os.getcwd() devuelve el directorio de trabajo del proceso. No siempre coincide con la carpeta donde está el script.

os.chdir("reports")
print(os.getcwd())

Cambiar la carpeta global puede dificultar el mantenimiento. En proyectos grandes suele ser mejor construir rutas explícitas. La guía de pathlib en Python muestra una alternativa orientada a objetos.

Listar archivos y carpetas

items = os.listdir(".")

for item in items:
    print(item)

listdir() devuelve nombres, no rutas completas. Para combinar la carpeta base:

folder = "documents"

for name in os.listdir(folder):
    full_path = os.path.join(folder, name)
    print(full_path)

La función os.scandir() puede ser más eficiente y ofrece información adicional:

with os.scandir(folder) as entries:
    for entry in entries:
        if entry.is_file():
            print("File:", entry.name)
        elif entry.is_dir():
            print("Folder:", entry.name)

Crear directorios

os.mkdir() crea una sola carpeta:

os.mkdir("output")

Si necesitas varios niveles, usa os.makedirs():

os.makedirs(
    "reports/2026/july",
    exist_ok=True,
)

exist_ok=True evita un error cuando el directorio ya existe.

Comprobar existencia y tipo

path = "data/sales.csv"

print(os.path.exists(path))
print(os.path.isfile(path))
print(os.path.isdir(path))

Estas comprobaciones son útiles, pero un archivo puede desaparecer entre la prueba y la operación. Para acciones críticas, también debes manejar excepciones. La guía de try y except en Python explica cómo responder a errores de permisos y rutas.

Combinar rutas correctamente

No concatenes separadores manualmente:

# Evitar
path = folder + "/" + filename

# Mejor
path = os.path.join(folder, filename)

os.path.join() utiliza el separador apropiado del sistema. Otras funciones útiles son:

print(os.path.basename(path))
print(os.path.dirname(path))
print(os.path.splitext(path))
print(os.path.abspath(path))

Renombrar y mover

os.rename(
    "reports/old.txt",
    "reports/new.txt",
)

os.replace() puede sustituir el destino cuando el sistema lo permite:

os.replace(
    "temp/report.tmp",
    "reports/report.txt",
)

Para mover archivos entre discos o copiar carpetas, shutil suele ser más adecuado. La guía de automatización de tareas con Python presenta organizadores de archivos y copias de seguridad.

Eliminar archivos y directorios

os.remove("temporary.txt")
os.rmdir("empty_folder")

os.rmdir() solo elimina carpetas vacías. Para un árbol completo, shutil.rmtree() es potente pero peligroso. Valida la ruta, utiliza copias y considera un modo de simulación antes de borrar.

Recorrer un árbol de carpetas

for root, directories, files in os.walk("project"):
    print("Folder:", root)

    for filename in files:
        full_path = os.path.join(root, filename)
        print("  ", full_path)

os.walk() resulta útil para buscar extensiones, calcular tamaños y crear inventarios.

Ejemplo: localizar archivos grandes

import os

LIMIT = 10 * 1024 * 1024

for root, _, files in os.walk("downloads"):
    for filename in files:
        path = os.path.join(root, filename)

        try:
            size = os.path.getsize(path)
        except OSError as error:
            print(f"No se pudo leer {path}: {error}")
            continue

        if size >= LIMIT:
            print(path, size)

Este ejemplo captura errores por archivo para que un elemento inaccesible no detenga todo el análisis.

Variables de entorno

os.environ ofrece acceso a las variables del proceso:

database_url = os.environ.get("DATABASE_URL")

if database_url is None:
    raise RuntimeError("Falta DATABASE_URL")

Para establecer una variable temporal dentro del proceso:

os.environ["APP_MODE"] = "development"

Las variables de entorno son apropiadas para configuración y secretos, pero no debes imprimirlas completas en logs.

Expandir rutas del usuario

home = os.path.expanduser("~")
config = os.path.expandvars(
    "$HOME/.config/myapp/settings.json"
)

El resultado depende del sistema y de las variables disponibles.

Información de archivos

stats = os.stat("report.txt")

print(stats.st_size)
print(stats.st_mtime)

Para convertir la marca temporal:

from datetime import datetime

modified = datetime.fromtimestamp(stats.st_mtime)
print(modified)

La guía de datetime en Python explica formatos y operaciones con fechas.

Ejemplo: organizar archivos por extensión

import os
import shutil

source = "incoming"

categories = {
    ".pdf": "documents",
    ".csv": "data",
    ".jpg": "images",
    ".png": "images",
}

for filename in os.listdir(source):
    current = os.path.join(source, filename)

    if not os.path.isfile(current):
        continue

    extension = os.path.splitext(filename)[1].lower()
    category = categories.get(extension, "other")
    target_folder = os.path.join(source, category)
    os.makedirs(target_folder, exist_ok=True)

    destination = os.path.join(target_folder, filename)

    if os.path.exists(destination):
        print("Destino existente:", destination)
        continue

    shutil.move(current, destination)

Antes de ejecutar una automatización destructiva, prueba con una carpeta de ejemplo y registra cada operación. La guía de logging en Python explica cómo guardar un historial.

os frente a pathlib

os sigue siendo útil para variables de entorno, permisos, procesos y funciones de bajo nivel. pathlib suele ofrecer una sintaxis más clara para rutas y archivos. Ambos módulos pueden utilizarse juntos:

from pathlib import Path
import os

base = Path(os.environ.get("APP_DATA", "."))
report = base / "reports" / "summary.txt"

Errores frecuentes

• Suponer que el directorio actual es la carpeta del script.
• Concatenar rutas con barras manualmente.
• Borrar directorios sin validar el destino.
• No manejar PermissionError o FileNotFoundError.
• Guardar secretos directamente en el código.
• Cambiar el directorio global sin necesidad.
• Ignorar diferencias entre sistemas operativos.

Fuentes oficiales

Además de la referencia principal de os, la documentación oficial de os.path describe las operaciones de rutas.

Conclusión

El módulo os permite consultar el entorno, crear carpetas, recorrer directorios, manipular rutas y leer configuración. Utiliza funciones portables, maneja excepciones y protege cualquier operación que pueda sobrescribir o eliminar datos. Para rutas modernas, combina estos conocimientos con pathlib.