PyYAML falla en Python 3.15 porque su última versión, la 6.0.3, no publica ruedas cp315: pip lo compila desde el código fuente, y el resultado depende de la versión que hayas fijado y de la imagen de Docker. Las versiones 6.0 y 5.4.1 terminan con AttributeError: 'build_ext' object has no attribute 'cython_sources'. La 6.0.3 se instala en python:3.15-slim sin avisar, pero sin libyaml, y el código que usa CSafeLoader deja de funcionar. Esta guía reproduce los dos errores y los arregla con una imagen multietapa. Lo probé el 11 de noviembre de 2026 en Linux arm64 con Docker 29.5.2, Python 3.15.2 y pip 26.2.2. Tienes la versión en inglés de esta guía.

Puntos clave

  • python:latest y python:slim apuntan a Python 3.15 desde octubre de 2026, y PyYAML 6.0.3 solo publica ruedas hasta cp314.
  • pip install pyyaml==6.0 y pyyaml==5.4.1 fallan en Python 3.15 con cython_sources; las versiones 6.0.1, 6.0.2 y 6.0.3 sí compilan.
  • En python:3.15-slim, la 6.0.3 se instala en Python puro: yaml.__with_libyaml__ vale False y yaml.CSafeLoader no existe.
  • Con libyaml, cargar un YAML de 377 KiB tardó 41 ms; sin libyaml, 299 ms.
  • Una imagen multietapa con gcc y libyaml-dev solo en la etapa de compilación ocupa 225 MB, frente a 496 MB si los dejas en la imagen final.

¿Por qué falla PyYAML en Python 3.15?

Falla porque pip no encuentra una rueda compilada para Python 3.15 y recurre al código fuente. La página de archivos de PyYAML 6.0.3 en PyPI[1] lista 73 archivos, publicados el 25 de septiembre de 2025, con ruedas de cp38 a cp314. Tres incidencias abiertas piden las de cp315 y suman 129 reacciones: la #951[2], la #981[3] y la #994[4]. La última lo resume así: "pyyaml is missing Python 3.15 wheels, thus blocking python 3.15 adoption".

El resultado de compilar cambia según la versión fijada. Esto es lo que hizo cada una en python:3.15-slim:

Versión fijada Resultado en python:3.15-slim
pyyaml==5.4.1 error cython_sources
pyyaml==6.0 error cython_sources
pyyaml==6.0.1, 6.0.2 se instala en Python puro, sin libyaml
pyyaml (6.0.3) se instala en Python puro, sin libyaml

Si quieres repasar el resto de cambios de la versión, tienes el resumen de las novedades de Python 3.15.

Error 1: AttributeError cython_sources con versiones fijadas

Este error aparece con pyyaml==6.0 y pyyaml==5.4.1, dos pines habituales en ficheros requirements.txt antiguos. pip descarga el .tar.gz y se detiene antes de compilar:

Getting requirements to build wheel: finished with status 'error'
  error: subprocess-exited-with-error
      AttributeError: 'build_ext' object has no attribute 'cython_sources'
ERROR: Failed to build 'pyyaml' when getting requirements to build wheel

La causa está en el pyproject.toml de esas versiones, que pide Cython sin límite de versión. pip instala Cython 3, que ya no tiene el atributo que usa el setup.py antiguo. Es el fallo de la incidencia #601 de PyYAML[5], abierta en enero de 2022, con 112 reacciones y 106 comentarios.

El arreglo es subir el pin a pyyaml==6.0.3. En las versiones anteriores de Python no lo notabas porque pip descargaba una rueda y nunca compilaba. El apaño clásico de limitar Cython no me funcionó en la 3.15: con PIP_CONSTRAINT apuntando a un fichero con cython<3, la 6.0 terminó con el mismo error.

Si el pin antiguo viene de una dependencia que no controlas, añade tu propia línea pyyaml==6.0.3 al fichero de restricciones y comprueba que su código no usa nada retirado en la serie 6.

Error 2: module 'yaml' has no attribute 'CSafeLoader'

Este es el fallo silencioso: en python:3.15-slim, pip install pyyaml termina con Successfully installed pyyaml-6.0.3 y nada avisa de que falta la parte en C. La imagen slim no trae compilador ni las cabeceras de libyaml, así que PyYAML construye una rueda de 45 KB solo con Python. Compruébalo con una línea:

python -c "import yaml; print(yaml.__version__, yaml.__with_libyaml__)"

En mi prueba devolvió 6.0.3 False. A partir de ahí, el código que pide el cargador en C falla al ejecutarse, no al instalar:

AttributeError: module 'yaml' has no attribute 'CSafeLoader'.
Did you mean '.SafeLoader' instead of '.CSafeLoader'?

ImportError: cannot import name 'CSafeLoader' from 'yaml'

El primer mensaje sale con yaml.CSafeLoader y el segundo con from yaml import CSafeLoader. Lo mismo ocurre con CLoader, CDumper y CSafeDumper.

Arreglo: compila PyYAML con libyaml en python:3.15-slim

PyYAML enlaza con libyaml cuando encuentra un compilador y las cabeceras al construir. En Debian 13, que es la base de python:3.15-slim, son los paquetes gcc, libc6-dev y libyaml-dev. Con ellos instalados, la rueda pasó de 45 KB a 635 KB y yaml.__with_libyaml__ devolvió True.

Para no cargar con el compilador en producción, construye la rueda en una etapa y cópiala a la imagen final, que solo necesita la biblioteca libyaml-0-2:

FROM python:3.15-slim AS build
RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      gcc libc6-dev libyaml-dev \
 && rm -rf /var/lib/apt/lists/*
RUN pip wheel --no-cache-dir --wheel-dir /wheels pyyaml==6.0.3

FROM python:3.15-slim
RUN apt-get update \
 && apt-get install -y --no-install-recommends libyaml-0-2 \
 && rm -rf /var/lib/apt/lists/*
COPY --from=build /wheels /wheels
RUN pip install --no-cache-dir --no-index --find-links /wheels \
      pyyaml==6.0.3 \
 && rm -rf /wheels

La opción --no-index obliga a pip a usar la rueda copiada y a fallar si no está, en lugar de volver a compilar sin libyaml. La imagen resultante devolvió 6.0.3 True y cargó un documento con CSafeLoader. El tamaño apenas cambia respecto a la base, mientras que dejar gcc en la imagen final la duplica con creces:

Tamaño de la imagen según cómo instalas PyYAML 6.0.3 MB · menos es mejor
python:3.15-slim sin PyYAML
208 MB
Multietapa, libyaml en la imagen final
225 MB
Una etapa, con gcc y libyaml-dev
496 MB
Ver tabla de valores
ImagenMB
python:3.15-slim sin PyYAML208 MB
Multietapa, libyaml en la imagen final225 MB
Una etapa, con gcc y libyaml-dev496 MB

Tamaños de docker images en Linux arm64 con Docker 29.5.2, 11 de noviembre de 2026.

El laboratorio de imágenes Docker multi-stage explica el patrón paso a paso con otro ejemplo.

Cuánto rendimiento pierdes sin libyaml

Sin libyaml, PyYAML funciona igual pero más despacio, así que el coste depende de cuánto YAML proceses. Medí la carga y el volcado de un documento con forma de fichero Compose: 2000 servicios, 22 001 líneas y 377 KiB. El cargador en C fue 7,3 veces más rápido y el volcador 4,4 veces:

Tiempo de carga y volcado de un YAML de 377 KiB con PyYAML 6.0.3 ms · menos es mejor
Carga (SafeLoader y CSafeLoader)
Python puro: 299 ms
libyaml: 41 ms
Volcado (SafeDumper y CSafeDumper)
Python puro: 155 ms
libyaml: 35 ms
Ver tabla de valores
OperaciónPython purolibyaml
Carga (SafeLoader y CSafeLoader)299 ms41 ms
Volcado (SafeDumper y CSafeDumper)155 ms35 ms

Python 3.15.2 en Docker sobre Linux arm64, mediana de 7 repeticiones, 11 de noviembre de 2026.

Para un servicio que lee un fichero de configuración al arrancar, 258 ms de diferencia no justifican una etapa de compilación. Para una herramienta que procesa miles de manifiestos, sí.

Alternativas: imagen completa, Python 3.14 o un cargador de reserva

Hay tres salidas que no exigen tocar el Dockerfile con apt-get, cada una con su coste:

  • Imagen completa: python:3.15 ya trae gcc y libyaml-dev, así que la 6.0.3 se compila con libyaml sin más pasos. Ocupa 1,64 GB frente a los 208 MB de la slim.
  • Python 3.14: en python:3.14-slim (3.14.10), pip descarga una rueda cp314 de 766 KB con libyaml incluida. Sirve si no necesitas nada de la 3.15, y pyyaml==6.0 falla allí igual, porque esa versión tampoco tiene rueda cp314.
  • Cargador de reserva: si el rendimiento no te importa, haz que el código acepte las dos variantes.

El cargador de reserva son dos líneas, y funcionan con y sin libyaml:

import yaml

Loader = getattr(yaml, "CSafeLoader", yaml.SafeLoader)

with open("config.yaml") as fichero:
    datos = yaml.load(fichero, Loader=Loader)

Mi recomendación es la imagen multietapa cuando el YAML está en el camino crítico, y el cargador de reserva en el resto de casos. Si además estás eligiendo imagen base, la comparativa de Wolfi, Alpine y distroless mide tamaños y vulnerabilidades.

Cómo detectar el problema en CI antes de desplegar

El riesgo de este cambio es que la instalación termina bien y el fallo aparece en producción. Dos comprobaciones lo convierten en un error de construcción. La primera prohíbe compilar desde el código fuente:

pip install --only-binary=:all: -r requirements.txt

En Python 3.15 termina con No matching distribution found for pyyaml, que es un mensaje más claro que un AttributeError en ejecución. La segunda comprueba la imagen ya construida:

python -c "import yaml, sys; sys.exit(not yaml.__with_libyaml__)"

El comando sale con código 1 cuando falta libyaml, así que puedes ponerlo como último RUN del Dockerfile.

Preguntas frecuentes

¿Cuándo publicará PyYAML ruedas para Python 3.15?

No hay fecha. A 11 de noviembre de 2026, las incidencias #951, #981 y #994 siguen abiertas y la última versión en PyPI es la 6.0.3. Cuando salgan, pip install pyyaml en la imagen slim descargará una rueda con libyaml y el segundo error desaparecerá, pero los pines 6.0 y 5.4.1 seguirán fallando.

¿Afecta a yamllint y a otras herramientas que dependen de PyYAML?

Depende de si usan los cargadores en C. yamllint==1.35.1 se instaló y analizó un fichero en python:3.15-slim sin errores, porque funciona con la versión en Python puro. Las herramientas que importan CSafeLoader sin alternativa fallan con el segundo error.

¿Sirve fijar Cython por debajo de la 3 para instalar PyYAML 6.0?

En Python 3.15 no me funcionó: con cython<3 en PIP_CONSTRAINT, la instalación de pyyaml==6.0 terminó con el mismo cython_sources. Subir a la 6.0.3 es el único arreglo que comprobé.

Conclusión

Los dos errores tienen el mismo origen, la falta de ruedas cp315, y arreglos distintos. Para cython_sources, sube el pin a pyyaml==6.0.3. Para CSafeLoader, compila con gcc y libyaml-dev en una etapa de construcción y deja libyaml-0-2 en la imagen final. Antes de cambiar nada, ejecuta python -c "import yaml; print(yaml.__with_libyaml__)" en tu imagen actual: si devuelve False, tu instalación ya está usando la versión lenta.

Fuentes: [1] PyYAML 6.0.3, archivos publicados en PyPI[1], [2] PyYAML, incidencia #951: Python 3.15 support[2], [3] PyYAML, incidencia #981: Publish wheels for Python 3.15[3], [4] PyYAML, incidencia #994: Please publish Python 3.15 wheels[4], [5] PyYAML, incidencia #601: AttributeError cython_sources[5], [6] Etiquetas de la imagen python en Docker Hub[6], [7] Documentación de PyYAML sobre los enlaces con LibYAML[7].

Fuentes

  1. página de archivos de PyYAML 6.0.3 en PyPI
  2. #951
  3. #981
  4. #994
  5. incidencia #601 de PyYAML
  6. Etiquetas de la imagen python en Docker Hub
  7. Documentación de PyYAML sobre los enlaces con LibYAML