Skip to main content

A lil' TOML parser

Project description

Build Status PyPI version


A lil' TOML parser

Table of Contents generated with mdformat-toc


Tomli is a Python library for parsing TOML. Tomli is fully compatible with TOML v1.0.0.


pip install tomli


Parse a TOML string

import tomli

toml_str = """
           gretzky = 99

           jari = 17

toml_dict = tomli.loads(toml_str)
assert toml_dict == {"gretzky": 99, "kurri": {"jari": 17}}

Parse a TOML file

import tomli

with open("path_to_file/conf.toml", encoding="utf-8") as f:
    toml_dict = tomli.load(f)

Handle invalid TOML

import tomli

    toml_dict = tomli.loads("]] this is invalid TOML [[")
except tomli.TOMLDecodeError:
    print("Yep, definitely not valid.")

Construct decimal.Decimals from TOML floats

from decimal import Decimal
import tomli

toml_dict = tomli.loads("precision-matters = 0.982492", parse_float=Decimal)
assert isinstance(toml_dict["precision-matters"], Decimal)

Note that you may replace decimal.Decimal with any callable that converts a TOML float from string to any Python type (except list or dict). The decimal.Decimal type is, however, the most typical replacement when float inaccuracies can not be tolerated.


Why this parser?

  • it's lil'
  • pure Python with zero dependencies
  • the fastest pure Python parser *: 10x as fast as tomlkit, 1.4x as fast as toml
  • outputs basic data types only
  • 100% spec compliant: passes all tests in a test set soon to be merged to the official compliance tests for TOML repository
  • thoroughly tested: 100% branch coverage

Is comment preserving round-trip parsing supported?


The tomli.loads function returns a plain dict that is populated with builtin types and types from the standard library only. Preserving comments requires a custom type to be returned so will not be supported, at least not by the tomli.loads function.

Is there a dumps, write or encode function?

Not yet, and it's possible there never will be.

This library is deliberately minimal, and most TOML use cases are read-only. Also, most use cases where writes are relevant could also benefit from comment and whitespace preserving reads, which this library does not currently support.

How do TOML types map into Python types?

TOML type Python type
Document Root dict
String str
Integer int
Float float
Boolean bool
Offset Date-Time datetime.datetime
Local Date-Time datetime.datetime
Local Date
Local Time datetime.time
Array list
Inline Table dict


The benchmark/ folder in this repository contains a performance benchmark for comparing the various Python TOML parsers. The benchmark can be run with tox -e benchmark-pypi. On June 1 2021 running the benchmark output the following on my notebook computer.

foo@bar:~/dev/tomli$ tox -e benchmark-pypi
benchmark-pypi installed: attrs==19.3.0,click==7.1.2,pytomlpp==1.0.2,qtoml==0.3.0,rtoml==0.6.1,toml==0.10.2,tomli==0.2.6,tomlkit==0.7.2
benchmark-pypi run-test-pre: PYTHONHASHSEED='3747534643'
benchmark-pypi run-test: commands[0] | python --version
Python 3.8.0
benchmark-pypi run-test: commands[1] | python benchmark/
Parsing data.toml 5000 times:
    parser |  exec time | performance (more is better)
  pytomlpp |     1.14 s | baseline (100%)
     rtoml |     1.16 s | 98.05%
     tomli |     6.72 s | 16.93%
      toml |     9.32 s | 12.19%
     qtoml |     15.3 s | 7.41%
   tomlkit |     67.2 s | 1.69%

The parsers are ordered from fastest to slowest, using the fastest parser (pytomlpp) as baseline. Tomli performed the best out of all pure Python TOML parsers, losing only to pytomlpp (wraps C++) and rtoml (wraps Rust).

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tomli-0.2.8.tar.gz (14.4 kB view hashes)

Uploaded Source

Built Distribution

tomli-0.2.8-py3-none-any.whl (10.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page