Python ConfigParser

The Story That Explains Config Files

This tutorial covers Python's configparser module end-to-end: reading INI files, extracting typed values, using the special DEFAULT section, variable interpolation, writing files back out, and where INI beats JSON/YAML/TOML and where it doesn't.

Anatomy of an INI File

Before writing any Python, understand the file format. INI files have exactly four building blocks — you'll never need a fifth.

Reading a Config File — The Basics

Step 1 — Create a Sample File

# app.ini
[database]
host = localhost
port = 5432
user = admin
password = secret

[server]
debug = true
timeout = 30
workers = 4

[logging]
level = INFO
file = /var/log/app.log

Step 2 — Read It From Python

import configparser

# Create a parser and load the file
config = configparser.ConfigParser()
config.read("app.ini")

# Dict-style access — the modern way
print(config["database"]["host"])         # localhost
print(config["database"]["port"])         # 5432  (still a STRING!)
print(config["logging"]["level"])         # INFO

# Method-style access — same result
print(config.get("database", "host"))       # localhost

All ConfigParser Methods — Reference

Iterating the Whole Config

import configparser

config = configparser.ConfigParser()
config.read("app.ini")

# Every section
for section in config.sections():
    print(f"[{section}]")
    for key, value in config.items(section):
        print(f"  {key} = {value}")
    print()

# Just the section names
print(config.sections())
# ['database', 'server', 'logging']

# Just the keys in one section
print(config.options("database"))
# ['host', 'port', 'user', 'password']

Checking Before Reading

import configparser

config = configparser.ConfigParser()
config.read("app.ini")

if config.has_section("cache"):
    ttl = config.getint("cache", "ttl")
else:
    ttl = 300  # fallback

if config.has_option("database", "replica_host"):
    replica = config["database"]["replica_host"]
else:
    replica = None

# Or use the fallback= parameter — cleaner
port = config.getint("database", "port", fallback=5432)
name = config.get("database", "name", fallback="myapp")

Getting Values with Proper Types

The getint, getfloat, and getboolean accessors do more than convert — they raise clear errors when the value can't be converted, saving you from silent bugs.

import configparser

config = configparser.ConfigParser()
config.read("app.ini")

# Integer — raises ValueError if not a valid integer
port = config.getint("database", "port")
print(port + 1)                          # 5433  (now it's a real int)

# Float
timeout = config.getfloat("server", "timeout")
print(type(timeout))                      # <class 'float'>

# Boolean — accepts many spellings
debug = config.getboolean("server", "debug")
print(debug)                             # True

# All of these are accepted for booleans:
#   True  ← yes, true, on, 1
#   False ← no, false, off, 0

# With fallback — no crash if the key is missing
workers = config.getint("server", "workers", fallback=4)

The DEFAULT Section — Shared Values

The [DEFAULT] section is magic. Every key you put there becomes automatically visible in every other section — unless that section overrides it. Perfect for values that apply broadly but vary in specific environments.

# app.ini
[DEFAULT]
log_level = INFO
timeout = 30
retries = 3

[production]
host = prod.db.co
log_level = WARN

[staging]
host = staging.db.co

[dev]
host = localhost
log_level = DEBUG

import configparser

config = configparser.ConfigParser()
config.read("app.ini")

# Notice: 'timeout' is NEVER defined in [staging] itself
# But it's readable because DEFAULT provides it
print(config["staging"]["host"])         # staging.db.co
print(config["staging"]["log_level"])    # INFO  (from DEFAULT)
print(config["staging"]["timeout"])      # 30   (from DEFAULT)

# [production] overrides log_level
print(config["production"]["log_level"]) # WARN (overridden)
print(config["production"]["timeout"])   # 30   (still from DEFAULT)

# sections() does NOT include DEFAULT — it's not a normal section
print(config.sections())
# ['production', 'staging', 'dev']

Interpolation — Variable Substitution

ConfigParser supports interpolation: values can reference other values using %(key)s syntax (basic) or ${section:key} syntax (extended). Great for building paths from base directories, or URLs from hostnames.

Basic Interpolation — Same Section Only

# app.ini
[paths]
home = /home/alice
data = %(home)s/data
logs = %(home)s/logs
backup = %(data)s/backups

import configparser

config = configparser.ConfigParser()
config.read("app.ini")

print(config["paths"]["home"])       # /home/alice
print(config["paths"]["data"])       # /home/alice/data
print(config["paths"]["logs"])       # /home/alice/logs
print(config["paths"]["backup"])     # /home/alice/data/backups

Extended Interpolation — Cross-Section References

# app.ini
[server]
host = example.com
port = 8080

[api]
base_url = https://${server:host}:${server:port}/api
health_url = ${base_url}/health
users_url = ${base_url}/users

import configparser

# Extended interpolation supports ${section:key} references
config = configparser.ConfigParser(
    interpolation=configparser.ExtendedInterpolation()
)
config.read("app.ini")

print(config["api"]["base_url"])
# https://example.com:8080/api

print(config["api"]["users_url"])
# https://example.com:8080/api/users

Writing & Updating Config Files

Modify Values in Memory, Then Save

import configparser

config = configparser.ConfigParser()
config.read("app.ini")

# Update an existing value — must be a STRING
config["database"]["port"] = "5433"

# Add a whole new section
config["cache"] = {
    "backend": "redis",
    "host": "cache.example.com",
    "ttl": "3600"
}

# Or add a new key to an existing section
config["server"]["host"] = "0.0.0.0"

# Write it back to disk
with open("app.ini", "w") as f:
    config.write(f)

Removing Sections and Options

import configparser

config = configparser.ConfigParser()
config.read("app.ini")

# Delete a single key
config.remove_option("database", "password")

# Delete a whole section (and all its keys)
config.remove_section("logging")

# Both return True if removed, False if it wasn't there

# Persist the changes
with open("app.ini", "w") as f:
    config.write(f)

Building a Config File From Scratch

import configparser

config = configparser.ConfigParser()

# Dict-of-dicts is the cleanest way to build
config["DEFAULT"] = {"log_level": "INFO", "timeout": "30"}
config["database"] = {
    "host": "localhost",
    "port": "5432",
    "user": "admin"
}
config["server"] = {
    "debug": "false",
    "workers": "4"
}

with open("new_config.ini", "w") as f:
    config.write(f)

Reading From Multiple Files

A powerful pattern: layer configs. Load a base config, then load an environment- specific one that overrides only what needs changing. Load a user config last for final overrides.

import configparser

config = configparser.ConfigParser()

# Files loaded LATER override values from earlier ones
config.read([
    "defaults.ini",       # shipped with the app
    "/etc/app.ini",       # system-wide config
    "~/.app.ini",          # user's home directory
    "./app.ini"            # current directory (highest priority)
])

# Missing files are silently skipped — read() returns the list of files
# that were actually loaded
loaded = config.read(["a.ini", "b.ini"])
print(f"Loaded: {loaded}")

Practical Real-World Examples

Example 1 — Database Connection From Config

import configparser

def get_db_config(path="app.ini"):
    config = configparser.ConfigParser()
    config.read(path)

    return {
        "host": config.get("database", "host", fallback="localhost"),
        "port": config.getint("database", "port", fallback=5432),
        "user": config.get("database", "user"),
        "password": config.get("database", "password"),
        "dbname": config.get("database", "dbname", fallback="myapp"),
    }

db = get_db_config()
print(f"Connecting to {db['host']}:{db['port']}")

Example 2 — Environment Switcher

import configparser
import os

env = os.getenv("APP_ENV", "dev")

config = configparser.ConfigParser()
config.read("config.ini")

# config.ini has [dev], [staging], [production] sections
# with a [DEFAULT] section for shared values
if not config.has_section(env):
    raise ValueError(f"Unknown environment: {env}")

active = config[env]
print(f"Running in {env} mode")
print(f"Database: {active['db_host']}")
print(f"Debug:    {config.getboolean(env, 'debug')}")

Example 3 — Feature Flags

import configparser

# flags.ini
# [features]
# dark_mode = true
# new_dashboard = false
# beta_analytics = on

config = configparser.ConfigParser()
config.read("flags.ini")

def flag_enabled(name):
    return config.getboolean("features", name, fallback=False)

if flag_enabled("dark_mode"):
    print("🌙  Using dark theme")

if flag_enabled("new_dashboard"):
    print("Loading new dashboard")
else:
    print("Loading classic dashboard")

Example 4 — API Client Setup

import configparser

config = configparser.ConfigParser(
    interpolation=configparser.ExtendedInterpolation()
)
config.read_string("""
[server]
protocol = https
host = api.example.com
port = 443

[endpoints]
base = ${server:protocol}://${server:host}:${server:port}
users = ${base}/v1/users
orders = ${base}/v1/orders
""")

print(config["endpoints"]["users"])
# https://api.example.com:443/v1/users

print(config["endpoints"]["orders"])
# https://api.example.com:443/v1/orders

Example 5 — Save User Preferences

import configparser
from pathlib import Path

CONFIG_PATH = Path.home() / ".myapp.ini"

def load_prefs():
    config = configparser.ConfigParser()
    if CONFIG_PATH.exists():
        config.read(CONFIG_PATH)
    return config

def save_prefs(config):
    with open(CONFIG_PATH, "w") as f:
        config.write(f)

# Load, modify, save
prefs = load_prefs()
if not prefs.has_section("ui"):
    prefs.add_section("ui")

prefs["ui"]["theme"] = "dark"
prefs["ui"]["font_size"] = "14"
prefs["ui"]["language"] = "en"

save_prefs(prefs)
print(f"Preferences saved to {CONFIG_PATH}")

INI vs JSON vs YAML vs TOML

ConfigParser handles INI files, but Python has options. Here's when to pick which.

Common Pitfalls

Golden Rules