Choosing the Right Config File Format in Python: INI, JSON, TOML, YAML Explained

Why Write a Configuration File

During development we often need fixed parameters or constants; storing them in a dedicated file keeps core code clean and avoids duplication across modules.

Common Configuration Formats

When the configuration must be shared across non‑Python platforms, generic formats are preferred. The most widely used are ini, json, toml, yaml and xml. All can be parsed with Python’s standard library or third‑party packages.

INI

INI (Initialize) originated on Windows. It consists of sections, keys and values.

[localdb]
host = 127.0.0.1
user = root
password = 123456
port = 3306
database = mysql

Python’s built‑in configparser reads INI files:

from configparser import ConfigParser
cfg = ConfigParser()
cfg.read("/Users/Bobot/db.ini")
print(cfg.items("localdb"))

Note that configparser returns all values as strings.

Example of converting the result to a dictionary and passing it to pymysql.connect:

import pymysql
from configparser import ConfigParser

cfg = ConfigParser()
cfg.read("/Users/Bobot/db.ini")
db_cfg = dict(cfg.items("localdb"))
con = pymysql.connect(**db_cfg)

JSON

JSON is a ubiquitous data‑exchange format and is also used for configuration files (e.g., npm, VSCode). Python’s json module can load files or strings.

{
    "localdb": {
        "host": "127.0.0.1",
        "user": "root",
        "password": "123456",
        "port": 3306,
        "database": "mysql"
    }
}

Loading the file:

import json
with open("/Users/Bobot/db.json") as j:
    cfg = json.load(j)["localdb"]
print(cfg)

JSON cannot contain comments and deep nesting can become error‑prone.

TOML

TOML was created by Tom Preston‑Werner. Its syntax is similar to INI but adds native support for timestamps, booleans, arrays, etc., and maps closely to Python data structures.

Example TOML file:

[mysql]
host = "127.0.0.1"
user = "root"
port = 3306
database = "test"

[mysql.parameters]
pool_size = 5
charset = "utf8"

[mysql.fields]
pandas_cols = ["id", "name", "age", "date"]

Parsing with the third‑party toml package:

import toml, os, pprint
cfg = toml.load(os.path.expanduser("~/Desktop/config.toml"))
pprint.pprint(cfg)

YAML

YAML (YAML Ain’t Markup Language) is popular for configuration (e.g., Docker Compose). It draws inspiration from Python and XML.

Loading a YAML file safely with PyYAML:

import yaml, os, pprint
with open(os.path.expanduser("~/config.yaml")) as f:
    cfg = yaml.safe_load(f)
pprint.pprint(cfg)

Using load() is unsafe because it can execute arbitrary Python objects; safe_load() should be preferred.

Conclusion

The article lists the main configuration formats and their Python reading methods. Their complexity increases roughly as ini < json ≈ toml < yaml. Choose the format that best fits your project’s needs and team workflow.