Type Stubs for TOML

0.10.8.20240310 verified Tue May 12 auth: no python install: verified

types-toml is a PEP 561 type stub package that provides static type annotations for the 'toml' library. It enables type-checking tools such as Mypy, Pyright, Pytype, and PyCharm to analyze code that interacts with TOML files, enhancing code reliability and maintainability. This package is automatically released, often daily, by the typeshed project, ensuring up-to-date type information for the `toml` package's 0.10.* versions.

pip install types-toml

Common errors

error error: Cannot find implementation or stub files for module 'toml' ↓

cause The Mypy type checker cannot find type definitions for the 'toml' library because the 'types-toml' stub package is not installed in your environment.

fix

Install the type stubs using pip: pip install types-toml

error Stub files for module 'toml' are not installed. ↓

cause Pyright requires separate type stub packages for libraries that don't include their own type annotations, and 'types-toml' is not installed in your environment.

fix

Install the type stubs using pip: pip install types-toml

error ImportError: cannot import name 'load' from 'types_toml' ↓

cause The 'types-toml' package provides static type annotations for the 'toml' library and is not meant to be imported or used directly at runtime.

fix

Import the desired functionality from the actual 'toml' library instead: from toml import load

Warnings

breaking As a stub-only package, any update to `types-toml` can introduce stricter or changed type annotations that might cause your code to fail type checking, even if the underlying `toml` runtime library hasn't changed. This is due to evolving type definitions in `typeshed` to better reflect runtime behavior or correct previous inaccuracies. ↓

fix Pin the `types-toml` version using `types-toml==X.Y.Z.YYYYMMDD` in your project's dependencies to ensure stability in type checking results. Regularly review `typeshed` changelogs for the `toml` stubs before updating.

gotcha When using `tomli.load()` or `tomllib.load()`, files must be opened in binary read mode (`'rb'`). Opening in text mode (`'r'`) will lead to `TypeError` or incorrect parsing due to UTF-8 decoding and universal newlines being handled by the parser itself. ↓

fix Always use `with open(filepath, 'rb') as f:` when loading TOML files with `tomli.load()` or `tomllib.load()`.

gotcha `types-toml` provides stubs for the `toml` package (and by extension `tomli`/`tomllib`). It does not install the runtime `toml` parser itself. Your project must explicitly install a TOML parser (e.g., `pip install toml` or `pip install tomli`). ↓

fix Ensure that a compatible runtime TOML parsing library (like `toml` or `tomli` for older Python versions, or relying on standard library `tomllib` for Python 3.11+) is installed alongside `types-toml`.

Install

pip install tomli # For Python < 3.11
pip install toml # For the runtime library

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) tomli - - - -

3.10 alpine (musl) types-toml wheel - - 17.8M

3.10 alpine (musl) types-toml - - - -

3.10 slim (glibc) tomli - - - -

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

3.10 slim (glibc) types-toml - - - -

3.11 alpine (musl) tomli - - - -

3.11 alpine (musl) types-toml wheel - - 19.6M

3.11 alpine (musl) types-toml - - - -

3.11 slim (glibc) tomli - - - -

3.11 slim (glibc) types-toml wheel 1.5s - 20M

3.11 slim (glibc) types-toml - - - -

3.12 alpine (musl) tomli - - - -

3.12 alpine (musl) types-toml wheel - - 11.5M

3.12 alpine (musl) types-toml - - - -

3.12 slim (glibc) tomli - - - -

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

3.12 slim (glibc) types-toml - - - -

3.13 alpine (musl) tomli - - - -

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

3.13 alpine (musl) types-toml - - - -

3.13 slim (glibc) tomli - - - -

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

3.13 slim (glibc) types-toml - - - -

3.9 alpine (musl) tomli - - - -

3.9 alpine (musl) types-toml wheel - - 17.3M

3.9 alpine (musl) types-toml - - - -

3.9 slim (glibc) tomli - - - -

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

3.9 slim (glibc) types-toml - - - -

Imports

load
```
import tomli # for Python < 3.11
# or
import tomllib # for Python >= 3.11
```
types-toml provides stubs for the 'toml' runtime library, or 'tomli'/'tomllib'. You import from the runtime library, and 'types-toml' provides the static typing support implicitly.
loads
```
import tomli # for Python < 3.11
# or
import tomllib # for Python >= 3.11
```
types-toml provides stubs for the 'toml' runtime library, or 'tomli'/'tomllib'. You import from the runtime library, and 'types-toml' provides the static typing support implicitly.

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to load a TOML file using either `tomllib` (Python 3.11+) or `tomli` (earlier versions), which are type-checked by `types-toml`. It highlights the typical use case of reading configuration and how type checkers would implicitly leverage the installed stubs to validate dictionary access patterns and expected types within the loaded TOML data.

import sys
from typing import Dict, Any

if sys.version_info >= (3, 11):
    import tomllib
else:
    import tomli as tomllib

def load_config(path: str) -> Dict[str, Any]:
    with open(path, 'rb') as f:
        config = tomllib.load(f)
    return config

# Example usage with a dummy config file
# Create a dummy config.toml for demonstration
with open('config.toml', 'w') as f:
    f.write('[database]\nhost = "localhost"\nport = 5432\n')

my_config = load_config('config.toml')
print(f"Database Host: {my_config['database']['host']}")
print(f"Database Port: {my_config['database']['port']}")

# With types-toml installed, type checkers will validate access patterns
# For example, my_config['non_existent_key'] would be flagged by a type checker.