Typing Stubs for PyYAML

6.0.12.20250915 verified Tue May 12 auth: no python install: verified quickstart: stale

This package provides static type annotations (stubs) for the PyYAML library. PyYAML is a full-featured YAML parser and emitter for Python, enabling seamless interaction with YAML data for configurations and structured data. Types-PyYAML allows static type checkers like mypy and pyright to analyze code using PyYAML, improving code quality and catching potential type errors before runtime. This package is part of the typeshed project and aims to provide accurate annotations for PyYAML versions 6.0.*.

pip install types-PyYAML

Common errors

error Cannot find implementation or library stub for module named 'yaml' ↓

cause The 'types-pyyaml' package, which provides static type stubs for the PyYAML library, is not installed or not accessible by MyPy.

fix

pip install types-pyyaml

error reportMissingTypeStubs: Stub file not found for 'yaml' ↓

cause The 'types-pyyaml' package, which provides static type stubs for the PyYAML library, is not installed or not accessible by Pyright.

fix

pip install types-pyyaml

error ModuleNotFoundError: No module named 'yaml' ↓

cause The 'PyYAML' runtime library is not installed; 'types-pyyaml' provides only static type annotations (stubs) and not the actual 'yaml' module for execution.

fix

pip install PyYAML

error Argument "Loader" to "load" of "yaml" has an incompatible type "Any"; expected "Union[Type[Loader], Type[SafeLoader], Type[FullLoader], Type[BaseLoader]]" ↓

cause MyPy is reporting a type incompatibility because 'yaml.load' is being called with a 'Loader' argument whose type is inferred as 'Any', often due to not explicitly specifying a safe loader or an untyped variable.

fix

Explicitly import and specify the desired Loader, for example:

from yaml import SafeLoader
data = yaml.load(yaml_string, Loader=SafeLoader)

Warnings

breaking Updates to type stubs, even without changes to your runtime code, can introduce new type-checking errors. This is because typeshed aims to improve the accuracy of type annotations, which might expose previously unflagged type inconsistencies in your codebase. ↓

fix Consider pinning your `types-PyYAML` version in your `requirements.txt` (e.g., `types-PyYAML==6.0.12.20250915`) and regularly testing updates. You can also temporarily ignore specific errors using `type: ignore` comments if a stub change is overly strict or controversial, while contributing fixes to typeshed.

gotcha When attempting to use the C-accelerated `CLoader` or `CDumper` from PyYAML with a fallback to pure Python `Loader`/`Dumper`, type checkers like mypy can report `Incompatible import` errors. This happens because `CLoader` and `Loader` are distinct types, even though they often serve a similar purpose. ↓

fix If strict type checking is desired, you may need to use `typing.cast` or `type: ignore` to suppress these specific errors. Alternatively, structure your code to use a single `Loader`/`Dumper` definition to avoid type checker confusion, or refactor to reduce direct exposure of the `Loader` type.

gotcha PyYAML (and thus its stubs) is based on the older YAML 1.1 specification. This can lead to unexpected implicit type conversions (e.g., 'yes', 'no' become booleans; '010' becomes an octal integer; `59:59` interpreted as seconds) compared to the stricter YAML 1.2 specification common in other parsers. The stubs accurately reflect these 1.1 behaviors. ↓

fix Be aware of YAML 1.1's implicit typing rules when writing or consuming YAML files with PyYAML. For stricter YAML 1.2 compliance, consider alternative libraries like `ruamel.yaml` if the `types-PyYAML` stubs' accuracy for PyYAML's behavior is undesirable for your use case.

gotcha The versioning of `types-PyYAML` is independent of `PyYAML` itself, though the stubs target specific `PyYAML` versions (e.g., `types-PyYAML 6.0.x.YYYYMMDD` targets `PyYAML==6.0.*`). This means updating one does not automatically update the other, and an older stub version might not fully cover a newer PyYAML, or vice versa. ↓

fix It is recommended to explicitly install both `PyYAML` and `types-PyYAML` and to regularly update both, while ensuring their compatibility. Typeshed recommends either using the same version bounds for stubs as for the package or pinning the stubs to a known good version.

Install

pip install PyYAML types-PyYAML mypy

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) PyYAML wheel - 0.09s 83.9M

3.10 alpine (musl) types-PyYAML wheel - - 17.9M

3.10 alpine (musl) PyYAML - - 0.09s 79.0M

3.10 alpine (musl) types-PyYAML - - - -

3.10 slim (glibc) PyYAML wheel 3.8s 0.05s 83M

3.10 slim (glibc) types-PyYAML wheel 1.5s - 18M

3.10 slim (glibc) PyYAML - - 0.05s 79M

3.10 slim (glibc) types-PyYAML - - - -

3.11 alpine (musl) PyYAML wheel - 0.23s 89.2M

3.11 alpine (musl) types-PyYAML wheel - - 19.7M

3.11 alpine (musl) PyYAML - - 0.27s 84.1M

3.11 alpine (musl) types-PyYAML - - - -

3.11 slim (glibc) PyYAML wheel 3.7s 0.20s 89M

3.11 slim (glibc) types-PyYAML wheel 1.6s - 20M

3.11 slim (glibc) PyYAML - - 0.20s 84M

3.11 slim (glibc) types-PyYAML - - - -

3.12 alpine (musl) PyYAML wheel - 0.14s 81.1M

3.12 alpine (musl) types-PyYAML wheel - - 11.6M

3.12 alpine (musl) PyYAML - - 0.16s 76.0M

3.12 alpine (musl) types-PyYAML - - - -

3.12 slim (glibc) PyYAML wheel 3.6s 0.16s 81M

3.12 slim (glibc) types-PyYAML wheel 1.4s - 12M

3.12 slim (glibc) PyYAML - - 0.17s 76M

3.12 slim (glibc) types-PyYAML - - - -

3.13 alpine (musl) PyYAML wheel - 0.13s 81.0M

3.13 alpine (musl) types-PyYAML wheel - - 11.3M

3.13 alpine (musl) PyYAML - - 0.15s 75.8M

3.13 alpine (musl) types-PyYAML - - - -

3.13 slim (glibc) PyYAML wheel 3.6s 0.15s 81M

3.13 slim (glibc) types-PyYAML wheel 1.4s - 12M

3.13 slim (glibc) PyYAML - - 0.16s 76M

3.13 slim (glibc) types-PyYAML - - - -

3.9 alpine (musl) PyYAML wheel - 0.07s 75.5M

3.9 alpine (musl) types-PyYAML wheel - - 17.4M

3.9 alpine (musl) PyYAML - - 0.08s 74.8M

3.9 alpine (musl) types-PyYAML - - - -

3.9 slim (glibc) PyYAML wheel 4.1s 0.06s 75M

3.9 slim (glibc) types-PyYAML wheel 1.7s - 18M

3.9 slim (glibc) PyYAML - - 0.07s 74M

3.9 slim (glibc) types-PyYAML - - - -

Imports

yaml
```
import yaml
```
Types-PyYAML provides type hints for the 'yaml' module imported from the PyYAML library. It does not introduce its own runtime symbols.
load, dump
```
from yaml import load, dump
```
Common imports for PyYAML functionality, now with type checking enabled by types-PyYAML.

Quickstart stale last tested: 2026-04-24

This quickstart demonstrates how `types-PyYAML` enables static type checking for `PyYAML` code using `mypy`. After installing `PyYAML`, `types-PyYAML`, and `mypy`, save the code to `app.py` and run `mypy app.py`. Mypy will detect the deliberate type error where an integer is assigned to a key expected to hold a string, thanks to the type information provided by `types-PyYAML`.

import yaml
from typing import Any

def process_config(config_str: str) -> dict[str, Any]:
    data: dict[str, Any] = yaml.safe_load(config_str)
    # Introduce a deliberate type error for demonstration
    # 'name' is expected to be a string, but we assign a number
    # mypy should flag this if types-PyYAML is correctly used.
    if 'name' in data: # type: ignore[reportUntypedBaseMembers]
        data['name'] = 123  # Intentionally wrong type for demo
    return data

config_data = """
name: Alice
age: 30
"""

# This would normally be executed, but the focus is on static analysis
# processed_data = process_config(config_data)
# print(processed_data)

# To run mypy and see the type error:
# 1. pip install PyYAML types-PyYAML mypy
# 2. Save this code as `app.py`
# 3. Run: `mypy app.py`
# Expected output should include a type error about data['name'] assignment.