You are currently viewing tomllib – Parse TOML files Using Python

tomllib – Parse TOML files Using Python

You might have seen files with the .toml extension in programming projects. What is that TOML?

TOML (Tom’s Obvious Minimal Language) files can be used to store application metadata in an easily readable format. Its format is extremely simple due to its minimal syntax.

The TOML file, like the JSON file in web development, is used to store application-specific configuration data, however, the syntax varies and is often preferred in projects where human readability and simplicity are prioritized.

In this article, you will learn how to parse TOML files with the Python standard library tomllib.


TOML file contains data in key-value pairs and has native types such as string, integer, float, booleans, tables, arrays, and more.

Here’s an example of a TOML file.

In the above file, title, owner, app, app.dependency, and database are the keys, and name, dob, app_name, version, etc., are the subkeys.

You can see values ["tomllib", "tomli"], [ ["delta", "phi"], [3.14] ] are array and array of tables respectively and value { cpu = 79.5, case = 72.0 } is an inline table.

If the above file is put into JSON land, it would give the following structure.

Now you can understand how TOML syntax works if you haven’t worked with the TOML files before.

You can use TOML for storing Python project metadata. See PEP 621 for more details.

tomllib – Parsing TOML Files

With the release of Python 3.11, the tomllib is added to the Python standard library to parse the TOML files using Python. This library is intended to read TOML files.

Having said that, the tomllib has only two functions: reading TOML from a file and loading TOML from a string.


tomllib.load(fp , parse_float=float)

The load() function reads a TOML file.


  • fp – A readable and binary file object. You can pass it positionally, but not as a keyword argument.
  • parse_float – You can specify a custom function for parsing the float in the TOML file. It defaults to using Python’s float() function. This is a keyword-only argument.

Return value:

  • The load() function returns the TOML file content in dictionary format.

tomllib.loads(s, parse_float=float)

The loads() function loads the TOML from a string object.


  • s or string – A string object that contains the TOML document.
  • parse_float – It is the same as the load() function’s parse_float.

Return value:

  • It also returns the results in dictionary format.

Parsing a TOML File

Here’s a config.toml file that contains some configuration data of an application written in TOML. You’ll use the tomllib‘s load() function to parse the file.

When you run the code, you’ll get the file’s content in a dictionary format.

Since the data is in dictionary format you can separate the keys and values from the data.

Now when you run this code, you’ll get the following result.

Exception Handling

The tomllib includes a TOMLDecodeError class that can handle errors encountered while decoding the TOML document.

As you can see, the code is wrapped in a try-except block, and any errors are handled by the tomllib.TOMLDecodeError in the except block.

Loading TOML from String

Assume you have a string with a TOML document. How do you parse that TOML? To achieve your desired result, use the tomllib.loads() function.

The variable my_toml contains a string of TOML, which is passed to the tomllib.loads() function.

As usual, this code will return a dictionary and you’ll get the following result.


So, if you write a configuration file or document in TOML and then want to parse it, you’ll know what to do.

You can use the tomllib library, which was included in the Python standard library with the release of Python 3.11. This library includes functions that can be used to read TOML files.

πŸ†Other articles you might be interested in if you liked this one

βœ…Split your string into an array of words using the split() method in Python.

βœ…Map a function to each item in an iterable using the map() function.

βœ…Serialize and deserialize Python objects using the pickle module.

βœ…Why if __name__ == β€˜__main__’ is used in Python programs?

βœ…Create a WebSocket server and client in Python.

βœ…Upload and display images on the frontend using Flask.

That’s all for now

Keep Coding✌✌