Install & Compatibility
Where this runs
tested against v0.10.8.20260518 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
toml
✓ import toml
✗ import toml-stubs
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.
Debug
Known issues
breakingAs 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.fixPin 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.
affects: All versions
gotchaWhen 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.fixAlways use `with open(filepath, 'rb') as f:` when loading TOML files with `tomli.load()` or `tomllib.load()`.
affects: All versions using tomli/tomllib
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`).fixEnsure 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`.
affects: All versions
Upgrade
Version history
0.10.8.20260518latest on PyPI · released May 18, 2026
Audit
Dependencies
tomlrequiredProvides the runtime functionality for TOML parsing and serialization that these stubs type-check. Used for toml==0.10.* versions.
tomlioptionalA TOML parser, often used for Python versions prior to 3.11 which introduced `tomllib` in the standard library.