Configparser

7.2.0 · active · verified Mon Apr 06

Configparser is a Python standard library module (also available as a backport for earlier Python versions) that provides tools for handling configuration files in INI format. It allows you to read, write, and manage user-editable configuration files, supporting features like sections, key-value pairs, default values, and value interpolation. The current backport version is 7.2.0 and it's actively maintained, periodically syncing with upstream CPython changes, making its features largely consistent with recent Python standard library versions.

Warnings

breaking The `SafeConfigParser` class and the `filename` parameter in `read()` were removed in version 6.0.0. The main `ConfigParser` class now incorporates the features previously found in `SafeConfigParser`.
Fix: Use `configparser.ConfigParser()` directly. The `read()` method now takes a path-like object or a list of path-like objects.
breaking As of version 7.0.0, the `configparser` top-level name from the backport package is removed for Python versions where `configparser` is already in the standard library (Python 3.9+). This ensures consistency with the standard library module.
Fix: On Python versions 3.9+, always use the standard library's `configparser`. The `pip install configparser` package is primarily for older Python versions (e.g., 3.6-3.8) to get updated features, or for specific pinning scenarios on newer Pythons where the stdlib version is masked by design.
gotcha ConfigParser treats all values as strings by default. To retrieve values as specific data types (integers, floats, booleans), use the dedicated `getint()`, `getfloat()`, and `getboolean()` methods.
Fix: Instead of `config['section']['key']`, use `config.getint('section', 'key')`, `config.getfloat('section', 'key')`, or `config.getboolean('section', 'key')`. Boolean values are case-insensitive and recognize '1', 'yes', 'true', 'on' as `True` and '0', 'no', 'false', 'off' as `False`.
gotcha Option names (keys) within sections are case-insensitive and are normalized to lowercase when accessed via dictionary-like syntax. However, section names *are* case-sensitive.
Fix: Always refer to options using lowercase for consistency, or be aware that `config['Section']['Key']` and `config['Section']['key']` will access the same value (assuming 'Section' matches case-sensitively).
gotcha The special `[DEFAULT]` section, while providing default values for other sections, is not returned by `config.sections()` or `config.has_section()`.
Fix: Access `DEFAULT` section options directly via `config.get('section', 'option', fallback=config['DEFAULT']['option'])` or treat `config['DEFAULT']` as a separate dictionary.
gotcha The `configparser` package is a backport. While `pip install configparser` works on Python >= 3.9 (as per its `requires_python` metadata), the module `configparser` is built into the standard library for all Python 3.x versions. Installing the backport on Python 3.9+ is often redundant unless specific backport features or fixes are needed that aren't yet in the stdlib of that particular Python version.
Fix: For Python 3.9 and newer, rely on the standard library `configparser` module unless you have a specific reason to install the backport (e.g., to access features not yet in your Python version's stdlib or for version pinning). For Python versions 2.6-3.8, `pip install configparser` (an older version of the backport) is necessary to use modern `configparser` features.

Install

pip install configparser Install the backport

Imports

ConfigParser
```
from configparser import ConfigParser
```
The module was renamed from `ConfigParser` to `configparser` in Python 3. `import configparser` followed by `configparser.ConfigParser()` is also common and correct.

Quickstart

This quickstart demonstrates how to create a configuration, write it to an INI file, and then read values back using the `ConfigParser` class. It shows basic section and option access, as well as using fallback values for non-existent options.

import configparser
import os

# Create a configuration file programmatically
config = configparser.ConfigParser()
config['DEFAULT'] = {
    'ServerAliveInterval': '45',
    'Compression': 'yes',
    'ForwardX11': 'yes'
}
config['production.server'] = {
    'User': 'prod_user',
    'Port': '50022',
    'ForwardX11': 'no'
}

config_file_path = 'example.ini'
with open(config_file_path, 'w') as configfile:
    config.write(configfile)

print(f"Configuration written to {config_file_path}")

# Read the configuration file
read_config = configparser.ConfigParser()
read_config.read(config_file_path)

# Access values using dictionary-like syntax
print(f"Compression for DEFAULT: {read_config['DEFAULT']['Compression']}")
print(f"User for production.server: {read_config['production.server']['User']}")

# Get a value with fallback
port = read_config.get('development.server', 'Port', fallback='22')
print(f"Port for development.server (with fallback): {port}")

# Clean up the created file
os.remove(config_file_path)
print(f"Cleaned up {config_file_path}")

view raw JSON →