Choosing the Right Config File Format for Python Projects: INI, JSON, TOML, YAML

Why Write Configuration Files

During development we often need fixed parameters or constants; storing them in a dedicated file keeps core code clean and avoids duplication across modules. While a .py file works for pure Python projects, cross‑language sharing benefits from a universal format.

INI

INI (Initialize) is a simple, section‑key‑value format popular on Windows.

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

Python’s built‑in configparser can parse INI files:

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

Note that configparser returns values as strings, which can be directly converted to a dictionary for unpacking into functions.

JSON

JSON is a widely used data‑exchange format and can also serve as a config file. Python’s json module reads JSON into dictionaries:

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

JSON’s strict syntax disallows comments and can become unwieldy with deeply nested structures.

TOML

TOML, introduced by GitHub co‑founder Tom Preston‑Werner, offers a more expressive syntax than INI while remaining easy to read. Install the parser with pip install toml and load files similarly to JSON:

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

TOML supports strings, timestamps, booleans, arrays, and maps, making it a good middle ground between INI and YAML.

YAML

YAML (or YML) is a popular, human‑friendly format used in tools like Docker Compose. Python’s PyYAML library parses YAML, but the unsafe load() function can execute arbitrary code. Use safe_load() instead:

import yaml
with open('config.yaml') as f:
    cfg = yaml.safe_load(f)
print(cfg)

YAML’s specification is extensive (over 80 pages), which can make it complex, but it remains powerful for hierarchical configurations.

Conclusion

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