Cómo arreglar los errores cython_sources y CSafeLoader de PyYAML en Python 3.15 con Docker
Índice de contenidos
- Puntos clave
- ¿Por qué falla PyYAML en Python 3.15?
- Error 1: AttributeError cython_sources con versiones fijadas
- Error 2: module 'yaml' has no attribute 'CSafeLoader'
- Arreglo: compila PyYAML con libyaml en python:3.15-slim
- Cuánto rendimiento pierdes sin libyaml
- Alternativas: imagen completa, Python 3.14 o un cargador de reserva
- Cómo detectar el problema en CI antes de desplegar
- Preguntas frecuentes
- ¿Cuándo publicará PyYAML ruedas para Python 3.15?
- ¿Afecta a yamllint y a otras herramientas que dependen de PyYAML?
- ¿Sirve fijar Cython por debajo de la 3 para instalar PyYAML 6.0?
- Conclusión
- Fuentes
PyYAML 6.0.3 no publica ruedas para Python 3.15, así que pip lo compila desde el código fuente. Las versiones fijadas 6.0 y 5.4.1 fallan con AttributeError: cython_sources, y la 6.0.3 se instala en python:3.15-slim sin libyaml, por lo que CSafeLoader no existe. Sube el pin a 6.0.3 e instala gcc y libyaml-dev al construir la imagen.
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:latestypython:slimapuntan a Python 3.15 desde octubre de 2026, y PyYAML 6.0.3 solo publica ruedas hastacp314.pip install pyyaml==6.0ypyyaml==5.4.1fallan en Python 3.15 concython_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__valeFalseyyaml.CSafeLoaderno existe. - Con libyaml, cargar un YAML de 377 KiB tardó 41 ms; sin libyaml, 299 ms.
- Una imagen multietapa con
gccylibyaml-devsolo 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:
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:
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.15ya traegccylibyaml-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 ruedacp314de 766 KB con libyaml incluida. Sirve si no necesitas nada de la 3.15, ypyyaml==6.0falla allí igual, porque esa versión tampoco tiene ruedacp314. - 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
Código fuente
Accede a todo el código fuente de este artículo en GitHub.
Ver en GitHub