Choosing the Right Config File Format for Python Projects

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 repetition across modules.

In Python we can use a .py file such as settings.py or config.py and import it directly, but for cross‑language sharing a language‑agnostic format is preferable. Common formats include ini, json, toml, yaml, and xml, all of which can be parsed with standard or third‑party libraries.

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 can read INI files:

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

Values are returned as strings, which is why the INI file does not require quotes.

After obtaining the key‑value pairs you can convert them to a dictionary and unpack them, e.g.:

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 widely used data‑exchange format and can also serve as a configuration file. It is easy to parse with Python’s json module.

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

Loading the file:

import json
from pprint import pprint

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

JSON’s strict syntax means it cannot contain comments and deep nesting can become hard to read.

TOML

TOML was proposed by Tom Preston‑Werner in 2013. Its syntax is similar to INI but adds support for timestamps, booleans, arrays, etc., and resembles native Python literals.

Example:

[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"]

Parse with the third‑party toml library:

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

YAML

YAML (or YML) is a popular configuration format introduced in 2001. It is used in many tools such as Docker Compose.

Python supports YAML via the PyYAML library. Use safe_load() instead of load() to avoid security risks.

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

Both json and yaml share a similar load() API, but load() can execute arbitrary code, so safe_load() is recommended.

Conclusion

The article lists common configuration file types 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.