Python ConfigParser

The Story That Explains Config Files 🍽️Config Files समझाने वाली कहानी 🍽️一个讲清配置文件的故事 🍽️

Anatomy of an INI File 🧬INI File की बनावट 🧬INI 文件的解剖 🧬

An INI file has only four building blocks. Everything else is just these, repeated.

INI file में सिर्फ़ चार building blocks होते हैं। बाक़ी सब इन्हीं का दोहराव है।

INI 文件只有四种构件，其余都是它们的重复。

Reading a Config File — The Basics 📖Config File पढ़ना — बुनियादी बातें 📖读取配置文件 — 基础 📖

All examples in this tutorial run next to a few small INI files. Here is the first one:

इस tutorial के सारे उदाहरण कुछ छोटी INI files के साथ चलते हैं। यह पहली है:

本教程的所有示例都与几个小 INI 文件放在一起运行。这是第一个：

# app.ini
# Main application settings
[database]
host = localhost
port = 5432
user = admin
password = s3cret

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

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

import configparser

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

print(config["database"]["host"])          # dict style
print(config.get("database", "host"))      # method style - same result
port = config["database"]["port"]
print(repr(port), type(port).__name__)     # still a STRING

try:
    print(port + 1)
except TypeError as e:
    print("TypeError:", e)

The Methods You Will Use 🧰जो Methods आप इस्तेमाल करेंगे 🧰你会用到的方法 🧰

Walking Through Everythingसब कुछ देखना遍历全部内容

import configparser

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

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

print(config.sections())
print(config.options("database"))
print("server" in config, "cache" in config)     # sections work with "in"
print("port" in config["database"])

Missing Keys and Fallbacksग़ायब Keys और Fallbacks缺失的键与后备值

import configparser

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

ttl = config.getint("cache", "ttl", fallback=300)          # no section -> fallback
name = config.get("database", "name", fallback="myapp")    # no option  -> fallback
print(ttl, name)

print(config.has_section("cache"), config.has_option("database", "host"))

try:
    config.get("database", "name")                          # no fallback
except configparser.NoOptionError as e:
    print(type(e).__name__ + ":", e)

config["database"]["port"] = "54x"                          # a broken value
try:
    config.getint("database", "port", fallback=5432)       # fallback does NOT help
except ValueError as e:
    print("ValueError:", e)

Getting Values with Proper Types 🔢सही Types के साथ Values पाना 🔢获取正确类型的值 🔢

import configparser

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

port = config.getint("database", "port")
print(port + 1)
timeout = config.getfloat("server", "timeout")
print(timeout, type(timeout).__name__)
print(config.getboolean("server", "debug"))

# Section proxies have the same getters
db = config["database"]
print(db.getint("port"), db.get("user"))

# Which words does getboolean understand?
for word in ["yes", "No", "ON", "off", "1", "0", "true", "FALSE", "maybe"]:
    config["server"]["flag"] = word
    try:
        print(f"{word!r:8} -> {config.getboolean('server', 'flag')}")
    except ValueError as e:
        print(f"{word!r:8} -> ValueError: {e}")

Try It — The INI Playground 🧪करके देखें — INI Playground 🧪动手试试 — INI 演练场 🧪

Type or paste any INI text. Each section appears as a card; keys that fall through from [DEFAULT] are dashed. Click a key to see what get, getint, getfloat and getboolean return. Try the trap presets — they are the bugs people really hit.

कोई भी INI text लिखें या paste करें। हर section एक card के रूप में दिखता है; [DEFAULT] से आने वाली keys dashed हैं। किसी key पर click करें और देखें कि get, getint, getfloat और getboolean क्या लौटाते हैं। Trap presets आज़माएँ — ये वही bugs हैं जिनसे लोग सच में टकराते हैं।

输入或粘贴任意 INI 文本。每个节显示为一张卡片；来自 [DEFAULT] 的键用虚线框表示。点击一个键，查看 get、getint、getfloat 和 getboolean 的返回值。试试陷阱预设 — 这些都是大家真实遇到过的 bug。

The DEFAULT Section — Shared Values ⤵️DEFAULT Section — साझा Values ⤵️DEFAULT 节 — 共享的值 ⤵️

Every key in [DEFAULT] is visible in every other section, unless that section sets its own value. Put shared settings there once, and override only what is different.

[DEFAULT] की हर key हर दूसरे section में दिखती है, जब तक वह section अपनी value न रखे। साझा settings वहाँ एक बार रखें, और सिर्फ़ जो अलग है उसे override करें।

[DEFAULT] 中的每个键在 所有 其他节中都可见，除非该节自己设置了值。把共享设置写一次放在那里，只覆盖不同的部分。

# envs.ini
[DEFAULT]
log_level = INFO
timeout = 30
retries = 3
debug = no

[production]
host = prod.db.example.com
log_level = WARNING

[staging]
host = staging.db.example.com

[dev]
host = localhost
log_level = DEBUG
debug = yes

import configparser

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

print(config["staging"]["host"])
print(config["staging"]["log_level"])      # from DEFAULT
print(config["production"]["log_level"])   # overridden
print(config.getboolean("dev", "debug"), config.getboolean("staging", "debug"))

print(config.sections())                   # DEFAULT is NOT listed
print(config.defaults())
print(config["DEFAULT"]["retries"])        # but you can still read it
print(config.options("staging"))           # includes the DEFAULT keys

Interpolation — Values That Use Other Values 🔗Interpolation — दूसरी Values इस्तेमाल करने वाली Values 🔗插值 — 引用其他值的值 🔗

Interpolation lets a value refer to another value, so you write a base path or host only once. ConfigParser uses BasicInterpolation by default: %(key)s looks in the same section or in DEFAULT.

Interpolation से एक value दूसरी value की ओर इशारा कर सकती है, ताकि base path या host एक ही बार लिखना पड़े। ConfigParser default रूप से BasicInterpolation इस्तेमाल करता है: %(key)s उसी section या DEFAULT में देखता है।

插值让一个值引用另一个值，这样基础路径或主机名只需写一次。ConfigParser 默认使用 BasicInterpolation：%(key)s 会在 同一节或 DEFAULT 中查找。

# paths.ini
[DEFAULT]
home = /home/priya

[paths]
data = %(home)s/data
logs = %(home)s/logs
backup = %(data)s/backups

import configparser

config = configparser.ConfigParser()      # BasicInterpolation is the default
config.read("paths.ini")

print(config["paths"]["data"])
print(config["paths"]["backup"])          # a chain: backup -> data -> home
print(config.get("paths", "backup", raw=True))   # raw=True: no substitution

ExtendedInterpolation — Across SectionsExtendedInterpolation — Sections के पारExtendedInterpolation — 跨节引用

# api.ini
[server]
protocol = https
host = api.example.com
port = 8443

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

import configparser

config = configparser.ConfigParser(interpolation=configparser.ExtendedInterpolation())
config.read("api.ini")

print(config["api"]["base_url"])
print(config["api"]["users_url"])
print(config["api"]["health_url"])

# secret.ini
[database]
password = 50%off!

import configparser

config = configparser.ConfigParser()
config.read("secret.ini")
try:
    print(config["database"]["password"])
except configparser.InterpolationSyntaxError as e:
    print(type(e).__name__ + ":", e)

# Fix 1: no interpolation at all
raw = configparser.ConfigParser(interpolation=None)
raw.read("secret.ini")
print(raw["database"]["password"])

# Fix 2: write %% in the file for a literal %
config.read_string("[database]\npassword = 50%%off!\n")
print(config["database"]["password"])

Parsing Rules That Surprise People 🪤Parsing के नियम जो लोगों को चौंकाते हैं 🪤让人意外的解析规则 🪤

Inline Comments Stay in the ValueInline Comments Value में ही रहते हैं行内注释会留在值里

# inline.ini
[server]
timeout = 30 ; seconds
host = 0.0.0.0  # listen on all interfaces

import configparser

config = configparser.ConfigParser()
config.read("inline.ini")
print(repr(config["server"]["timeout"]))
print(repr(config["server"]["host"]))
try:
    config.getint("server", "timeout")
except ValueError as e:
    print("ValueError:", e)

# Tell the parser which inline comment markers to allow
config = configparser.ConfigParser(inline_comment_prefixes=(";", "#"))
config.read("inline.ini")
print(config.getint("server", "timeout"), repr(config["server"]["host"]))

Keys Are Lowercase, Sections Are NotKeys lowercase हैं, Sections नहीं键不分大小写，节分

import configparser

config = configparser.ConfigParser()
config.read_string("""
[Server]
Port = 8080
""")
print(config.sections())                     # section names keep their case
print(config["Server"]["PORT"], config["Server"]["port"])   # keys do not
print(list(config["Server"]))
print("server" in config)                    # sections ARE case-sensitive

keep = configparser.ConfigParser()
keep.optionxform = str                       # keep key case as written
keep.read_string("[Server]\nPort = 8080\n")
print(list(keep["Server"]))

Multi-line Values and Strict ErrorsMulti-line Values और Strict Errors多行值与严格模式错误

import configparser

config = configparser.ConfigParser()
config.read_string("""
[email]
signature = Regards,
    Priya Sharma
    Baddi, Himachal Pradesh
""")
print(config["email"]["signature"])           # indented lines continue the value

for text in ["host = x\n[a]\n", "[a]\nx = 1\nx = 2\n", "[a]\n[a]\n", "[a]\njust a line\n"]:
    try:
        configparser.ConfigParser().read_string(text)
    except configparser.Error as e:
        print(type(e).__name__ + ":", str(e).splitlines()[0])

Writing and Updating Config Files ✍️Config Files लिखना और बदलना ✍️写入与更新配置文件 ✍️

# messy.ini
# Team settings - edit with care!
[Server]
Host = 0.0.0.0     
Port = 8080
; old value: 8000

[Database]
URL = postgres://db.local/app
Password = hunter2

import configparser, io

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

config["Server"]["port"] = "9090"                  # values must be strings
config["cache"] = {"backend": "redis", "ttl": 3600}  # dicts are converted with str()
config.remove_option("Database", "password")

try:
    config.set("Server", "workers", 4)             # a plain int is refused
except TypeError as e:
    print("TypeError:", e)

out = io.StringIO()
config.write(out)                                   # usually: open("app.ini", "w")
print(out.getvalue())

import configparser

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

print(config.remove_option("database", "password"))   # True: it was there
print(config.remove_option("database", "password"))   # False: already gone
print(config.remove_section("logging"))               # True
print(config.sections())

Building a File from Scratchशुरू से File बनाना从零创建文件

import configparser, sys

config = configparser.ConfigParser()
config["DEFAULT"] = {"log_level": "INFO", "timeout": "30"}
config["database"] = {"host": "localhost", "port": "5432"}
config["server"] = {"debug": "false", "workers": "4"}

config.write(sys.stdout)    # in real code: with open("new.ini", "w") as f: config.write(f)

Try It — Write Round-Tripकरके देखें — Write Round-Trip动手试试 — 写回往返

Step through a real session: read a file, change it in memory, then write(). At the last step, red lines in the old file were lost and green lines in the new file are new. Every message is exactly what Python 3.13 printed.

एक असली session में कदम-दर-कदम चलें: file पढ़ें, memory में बदलें, फिर write() करें। आख़िरी कदम पर पुरानी file की लाल lines खो गईं और नई file की हरी lines नई हैं। हर संदेश ठीक वही है जो Python 3.13 ने छापा।

逐步走完一次真实的会话：读取文件、在内存中修改，然后 write()。在最后一步，旧文件中的红色行已丢失，新文件中的绿色行是新增的。每条信息都与 Python 3.13 打印的完全一致。

Layered Config from Several Files 🥞कई Files से परतदार Config 🥞来自多个文件的分层配置 🥞

Professional apps load several files in order: defaults shipped with the app, then a system file, then the user's file, then a local file. Each layer changes only what it cares about; a later file wins.

Professional apps कई files क्रम से load करते हैं: app के साथ आए defaults, फिर system file, फिर user की file, फिर local file। हर परत सिर्फ़ वही बदलती है जिसकी उसे परवाह है; बाद वाली file जीतती है।

专业应用会按顺序加载多个文件：随应用发布的默认值、系统文件、用户文件，最后是本地文件。每一层只改它关心的部分；后加载的文件获胜。

import configparser
from pathlib import Path

config = configparser.ConfigParser()
loaded = config.read([
    "defaults.ini",                    # shipped with the app
    "etc_app.ini",                     # system-wide (e.g. /etc/app.ini)
    Path.home() / ".app.ini",          # the user's own file - may not exist
    "local_app.ini",                   # this folder: highest priority
])
print("Loaded:", loaded)
for section in config.sections():
    print(section, dict(config[section]))

print(config.read("~/.app.ini"))       # read() does NOT expand ~ : nothing loaded

Try It — Layered Config Stackकरके देखें — Layered Config Stack动手试试 — 分层配置栈

Click a layer to remove or restore its file. The merged result shows which file each value came from. All 16 combinations were computed by Python.

किसी layer पर click करके उसकी file हटाएँ या वापस लाएँ। मिला हुआ नतीजा दिखाता है कि हर value किस file से आई। सभी 16 combinations Python ने निकाले हैं।

点击某一层可以移除或恢复它的文件。合并结果会显示每个值来自哪个文件。全部 16 种组合都由 Python 计算得出。

When a File Is Requiredजब File ज़रूरी हो当文件是必需的

import configparser

config = configparser.ConfigParser()
print(config.read("missing.ini"))            # [] - silent!

try:
    with open("missing.ini", encoding="utf-8") as f:
        config.read_file(f)                  # a required file: fail loudly
except FileNotFoundError as e:
    print("FileNotFoundError:", e)

Local PC vs Server — One Code, the Right Settings Everywhere 🌍Local PC बनाम Server — एक Code, हर जगह सही Settings 🌍本地电脑与服务器 — 同一份代码，处处正确的设置 🌍

Here is the real-life question: the same code runs on your laptop and on the server. On your PC you want debug on, a local database and your own password. On the server you want debug off, the real database, and a password that is never stored in Git. How does the code know where it is running, and pick the right values?

असली सवाल यह है: वही code आपके laptop पर भी चलता है और server पर भी। PC पर आपको debug चालू, local database और अपना password चाहिए। Server पर debug बंद, असली database, और ऐसा password चाहिए जो Git में कभी न रखा जाए। Code को कैसे पता चले कि वह कहाँ चल रहा है, और वह सही values कैसे चुने?

现实中的问题是：同一份代码 既在你的笔记本上运行，也在服务器上运行。在电脑上，你希望开启调试、使用本地数据库和自己的密码。在服务器上，你希望关闭调试、使用真实数据库，并且密码 绝不 存进 Git。代码怎么知道自己运行在哪里，并选出正确的值？

The answer is a small loader with one switch and layers: the environment variable APP_ENV says which environment this is, and settings are stacked so that later layers win.

जवाब है एक छोटा loader जिसमें एक switch और परतें हैं: environment variable APP_ENV बताता है कि यह कौन-सा environment है, और settings ऐसे ढेर की जाती हैं कि बाद की परत जीते।

答案是一个小加载器，包含 一个开关 和 多个层：环境变量 APP_ENV 说明当前是哪个环境，设置按层叠加，后面的层获胜。

The Project LayoutProject की बनावट项目结构

billing/
├── main.py
├── settings.py          # the loader
├── config/
│   ├── base.ini          # ✅ in Git
│   ├── development.ini   # ✅ in Git
│   ├── production.ini    # ✅ in Git - no passwords!
│   └── local.ini         # ❌ NOT in Git - your PC only
└── .gitignore            # contains: config/local.ini

# config/base.ini
# Shared by every machine - committed to Git
[app]
name = Billing
log_level = INFO

[database]
host = localhost
port = 5432
name = billing
user = billing_app
password =

[server]
debug = false
port = 8000

# config/development.ini
# Your PC - committed to Git
[app]
log_level = DEBUG

[server]
debug = true

# config/production.ini
# The server - committed to Git, but NO passwords here
[database]
host = db.internal.example.com
name = billing_prod

[server]
port = 80

# config/local.ini
# Only on YOUR PC - listed in .gitignore, never committed
[database]
port = 5433
password = my-local-pass

The Loader — settings.pyLoader — settings.py加载器 — settings.py

# settings.py
import configparser
import os
from pathlib import Path

# Find config/ next to THIS file - not in whatever folder the server starts in
CONFIG_DIR = Path(__file__).resolve().parent / "config"

def load_settings():
    env = os.getenv("APP_ENV", "development")       # your PC: nothing to set
    config = configparser.ConfigParser(interpolation=None)

    env_file = CONFIG_DIR / f"{env}.ini"
    if not env_file.exists():                       # a typo must fail loudly
        raise FileNotFoundError(f"No config for APP_ENV={env!r}: {env_file.name}")

    loaded = config.read([
        CONFIG_DIR / "base.ini",                    # 1. shared by everyone
        env_file,                                   # 2. development.ini / production.ini
        CONFIG_DIR / "local.ini",                   # 3. this PC only (in .gitignore)
    ], encoding="utf-8")

    # 4. Environment variables win over every file: APP_<SECTION>_<KEY>
    for section in config.sections():
        for key in config[section]:
            name = f"APP_{section}_{key}".upper()
            if name in os.environ:
                config[section][key] = os.environ[name]

    # 5. Secrets come ONLY from the environment on a server
    if "DB_PASSWORD" in os.environ:
        config["database"]["password"] = os.environ["DB_PASSWORD"]
    if env == "production" and not config["database"]["password"]:
        raise RuntimeError("DB_PASSWORD must be set on the server")

    return config, env, loaded

# main.py
from pathlib import Path
from settings import load_settings

config, env, loaded = load_settings()
db = config["database"]
print("Environment :", env)
print("Loaded      :", [Path(p).name for p in loaded])
print("Database    :", f"{db['user']}@{db['host']}:{db.getint('port')}/{db['name']}")
print("Password set:", bool(db["password"]))
print("Debug       :", config.getboolean("server", "debug"))
print("Log level   :", config["app"]["log_level"])
print("Server port :", config.getint("server", "port"))

The Same Code, Run in Two Placesवही Code, दो जगह चलाया गया同一份代码，在两处运行

First on your PC — nothing set, local.ini present. Then on the server — APP_ENV=production and DB_PASSWORD set, no local.ini. Both outputs are real runs.

पहले आपके PC पर — कुछ set नहीं, local.ini मौजूद। फिर server पर — APP_ENV=production और DB_PASSWORD set, local.ini नहीं। दोनों outputs असली runs हैं।

先在你的电脑上 — 什么都没设置，有 local.ini。再在服务器上 — 设置了 APP_ENV=production 和 DB_PASSWORD，没有 local.ini。两段输出都是真实运行结果。

$ python main.py

$ export APP_ENV=production
$ export DB_PASSWORD='Pr0d-S3cret!'
$ python main.py

How to Set APP_ENV on Each Machineहर मशीन पर APP_ENV कैसे set करें如何在各种机器上设置 APP_ENV

Try It — Where Am I Running?करके देखें — मैं कहाँ चल रहा हूँ?动手试试 — 我在哪里运行？

Pick a machine, or set each switch yourself. The console shows the real output of python main.py for that exact setup — all 32 combinations were run with Python 3.13. Try the presets with ⚠️: they are the mistakes that cause real outages.

एक मशीन चुनें, या हर switch ख़ुद set करें। Console उसी setup के लिए python main.py का असली output दिखाता है — सभी 32 combinations Python 3.13 से चलाए गए। ⚠️ वाले presets आज़माएँ: यही गलतियाँ असली outages करती हैं।

选择一台机器，或者自己设置每个开关。控制台会显示该配置下 python main.py 的真实输出 — 全部 32 种组合都用 Python 3.13 运行过。试试带 ⚠️ 的预设：它们正是导致真实故障的错误。

Real-World Recipes 🛠️असली काम की Recipes 🛠️实战配方 🛠️

1 · Environment Switcher1 · Environment बदलना1 · 环境切换

One file, several environments. An environment variable decides which section is active; [DEFAULT] fills in the rest.

एक file, कई environments। एक environment variable तय करता है कि कौन-सा section चालू है; बाक़ी [DEFAULT] भरता है।

一个文件，多个环境。由一个环境变量决定使用哪个节；其余部分由 [DEFAULT] 补上。

import configparser, os

os.environ.setdefault("APP_ENV", "staging")        # normally set outside Python
env = os.environ["APP_ENV"]

config = configparser.ConfigParser()
config.read("envs.ini")
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['host']}")
print(f"Debug:    {active.getboolean('debug')}")
print(f"Retries:  {active.getint('retries')}")

2 · Feature Flags2 · Feature Flags2 · 功能开关

import configparser

config = configparser.ConfigParser()
config.read_string("""
[features]
dark_mode = true
new_dashboard = off
beta_analytics = yes
""")

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

for name in ["dark_mode", "new_dashboard", "beta_analytics", "voice_search"]:
    print(f"{name:15} {flag_enabled(name)}")

3 · Saving User Preferences3 · User Preferences save करना3 · 保存用户偏好

import configparser
from pathlib import Path

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

def load_prefs():
    config = configparser.ConfigParser()
    config.read(CONFIG_PATH)            # fine if the file does not exist yet
    return config

def save_prefs(config):
    with open(CONFIG_PATH, "w", encoding="utf-8") as f:
        config.write(f)

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"] = "hi"
save_prefs(prefs)

print("Saved to", CONFIG_PATH)
print(CONFIG_PATH.read_text(encoding="utf-8"))
print(load_prefs().getint("ui", "font_size"))

INI vs JSON vs YAML vs TOML ⚖️INI बनाम JSON बनाम YAML बनाम TOML ⚖️INI、JSON、YAML 与 TOML ⚖️

# pyproject.toml
[project]
name = "billing"
version = "1.4.0"
dependencies = ["requests>=2.32", "rich"]

[tool.billing]
retries = 3
debug = false
timeout = 2.5

import tomllib       # Python 3.11+: read TOML with no extra package

with open("pyproject.toml", "rb") as f:   # tomllib needs binary mode
    data = tomllib.load(f)

print(data["project"]["dependencies"])     # a real list
cfg = data["tool"]["billing"]
print(cfg)                                  # real int, bool and float
print(type(cfg["retries"]).__name__, type(cfg["debug"]).__name__)

New in Python 3.13: Keys Before Any SectionPython 3.13 में नया: किसी Section से पहले KeysPython 3.13 新增：节之前的键

import configparser

# Python 3.13+: keys before the first [section] are allowed if you ask
config = configparser.ConfigParser(allow_unnamed_section=True)
config.read_string("""
version = 2
[app]
name = billing
""")
print(config.get(configparser.UNNAMED_SECTION, "version"))
print(config["app"]["name"])

Common Pitfalls 🕳️आम ग़लतियाँ 🕳️常见陷阱 🕳️

Golden Rules and Quiz 🏆सुनहरे नियम और Quiz 🏆黄金法则与小测验 🏆

Quick Quiz — 8 Questionsछोटा Quiz — 8 सवाल小测验 — 8 道题