Cómo resolver errores de codificación UTF-8 en Python

Los errores de codificación UTF-8 aparecen cuando un programa confunde texto con bytes o cuando dos sistemas no comparten el mismo formato. Los síntomas incluyen UnicodeDecodeError, UnicodeEncodeError, acentos convertidos en símbolos extraños y archivos que funcionan en una computadora pero fallan en otra. La solución empieza por comprender dónde ocurre cada conversión.

Python 3 representa el texto con str y los datos binarios con bytes. Al leer un archivo o una respuesta de red, los bytes deben decodificarse. Al escribir o enviar texto, debe codificarse. UTF-8 es una excelente opción predeterminada porque puede representar todos los caracteres Unicode y es ampliamente compatible.

La diferencia entre str y bytes

texto = "Programación"
datos = texto.encode("utf-8")

print(type(texto))
print(type(datos))
print(datos)

encode() convierte texto en bytes. Para recuperar la cadena:

recuperado = datos.decode("utf-8")
print(recuperado)

La codificación utilizada para decodificar debe coincidir con la utilizada para codificar. Si no conoces el origen, no debes adivinar sin verificar.

Abrir archivos con encoding explícito

from pathlib import Path

ruta = Path("informe.txt")
contenido = ruta.read_text(encoding="utf-8")

Al escribir:

ruta.write_text("Información actualizada", encoding="utf-8")

La guía de archivos de texto en Python explica lectura por líneas, contexto y manejo de errores. Evitar la codificación predeterminada del sistema hace el comportamiento más reproducible.

Diagnosticar UnicodeDecodeError

Este error ocurre cuando una secuencia de bytes no es válida para el codec elegido:

with open("datos.txt", encoding="utf-8") as archivo:
    contenido = archivo.read()

Si el archivo es Windows-1252, debes abrirlo con esa codificación y luego convertirlo:

from pathlib import Path

origen = Path("datos.txt")
texto = origen.read_text(encoding="cp1252")

Path("datos_utf8.txt").write_text(texto, encoding="utf-8")

La guía específica para corregir UnicodeDecodeError presenta detección y fallbacks.

Diagnosticar UnicodeEncodeError

Este error aparece al intentar representar un carácter con una codificación que no lo admite:

texto = "Precio: 20 €"
datos = texto.encode("ascii")

ASCII no contiene el símbolo del euro. UTF-8 sí:

datos = texto.encode("utf-8")

No elimines caracteres legítimos para satisfacer una codificación limitada salvo que el formato externo lo exija y exista una regla de transliteración documentada.

Qué es el mojibake

El mojibake es texto mal interpretado, por ejemplo Programación. Puede ocurrir cuando bytes UTF-8 se decodifican como Latin-1 y después se vuelven a codificar. A diferencia de una excepción, el resultado sigue siendo texto válido, por lo que el problema puede pasar desapercibido.

original = "Programación"
incorrecto = original.encode("utf-8").decode("latin-1")
print(incorrecto)

La prevención es más segura que intentar reparar múltiples conversiones. Documenta el encoding en cada frontera.

UTF-8 con BOM

Algunos archivos incluyen una marca al comienzo. Para leerlos sin conservar el carácter invisible, utiliza utf-8-sig:

with open("exportacion.csv", encoding="utf-8-sig") as archivo:
    contenido = archivo.read()

Al escribir para programas que esperan BOM:

with open("salida.csv", "w", encoding="utf-8-sig", newline="") as archivo:
    archivo.write("nombre,ciudad\nAna,Málaga\n")

Archivos CSV

Especifica encoding y newline="":

import csv

with open("clientes.csv", encoding="utf-8", newline="") as archivo:
    lector = csv.DictReader(archivo)
    for fila in lector:
        print(fila)

Para crear archivos:

with open("salida.csv", "w", encoding="utf-8", newline="") as archivo:
    escritor = csv.writer(archivo)
    escritor.writerow(["nombre", "ciudad"])
    escritor.writerow(["José", "Bogotá"])

Consulta la guía de CSV en Python para dialectos, encabezados y procesamiento por streaming.

Respuestas HTTP

Las APIs suelen declarar el charset en Content-Type. Con Requests puedes trabajar con bytes o texto:

import requests

respuesta = requests.get("https://example.com/api", timeout=10)
respuesta.raise_for_status()

print(respuesta.encoding)
datos_binarios = respuesta.content
texto = respuesta.text

Para JSON, utiliza response.json() cuando el servidor envía un documento válido. La guía de Requests en Python explica cabeceras, timeouts y errores.

La consola y el sistema operativo

La codificación de la terminal puede diferir de la del archivo. Inspecciona:

import sys

print(sys.stdout.encoding)
print(sys.stdin.encoding)

En entornos administrados puedes configurar UTF-8 mediante las opciones del intérprete o variables apropiadas, pero evita cambiar configuraciones globales sin comprender el impacto. Si rediriges salida a un archivo, define el encoding en el destino cuando sea posible.

errors: strict, replace e ignore

texto = datos.decode("utf-8", errors="replace")

strict es el comportamiento predeterminado y lanza una excepción. replace coloca un marcador y ignore elimina datos. Para información importante, mantén strict, captura el error y revisa la fuente. replace puede servir para mostrar una previsualización sin detener toda la aplicación.

Normalización Unicode

Dos cadenas visualmente iguales pueden utilizar secuencias distintas de code points. Esto afecta búsquedas, comparaciones y claves:

import unicodedata

normalizado = unicodedata.normalize("NFC", texto)

NFC es una opción común para texto general. La normalización no corrige una decodificación equivocada; debe aplicarse después de obtener el texto correcto.

Leer archivos grandes

No necesitas cargar todo el contenido para validar UTF-8:

with open("archivo_grande.txt", encoding="utf-8") as archivo:
    for numero, linea in enumerate(archivo, start=1):
        procesar(linea)

Si ocurre un error, registra la ruta y el contexto sin exponer información sensible. Utiliza pathlib para administrar ubicaciones de forma multiplataforma.

Probar con caracteres variados

muestra = "Español: ñ | Português: ã | 日本語 | 😀"

datos = muestra.encode("utf-8")
assert datos.decode("utf-8") == muestra

Añade pruebas con acentos, símbolos monetarios, alfabetos no latinos y emojis si la aplicación los acepta. Un conjunto de pruebas limitado a ASCII no detectará muchos problemas reales.

Fuentes oficiales

La guía oficial de Unicode de Python explica code points, encodings y procesamiento. La documentación del módulo codecs describe codecs, manejadores de errores y utilidades relacionadas.

Errores frecuentes

Los fallos habituales son abrir archivos sin encoding explícito, usar Latin-1 para evitar excepciones, combinar str y bytes, decodificar dos veces, confiar ciegamente en detección automática y usar ignore en datos críticos. Otro error es pensar que UTF-8 significa solamente idiomas occidentales; puede representar todo Unicode.

Conclusión

Resolver errores UTF-8 requiere identificar cada frontera entre texto y bytes. Define UTF-8 como estándar interno, especifica el encoding al leer y escribir, respeta el formato declarado por servicios externos y conserva los bytes originales durante el diagnóstico. Utiliza normalización para comparaciones coherentes y pruebas con caracteres reales. Con contratos claros, la codificación deja de ser un problema imprevisible y se convierte en una decisión explícita del sistema.