Skip to main content

Updated configparser from Python 3.7 for Python 2.6+.

Project description

The ancient ConfigParser module available in the standard library 2.x has seen a major update in Python 3.2. This is a backport of those changes so that they can be used directly in Python 2.6 - 3.5.

To use the configparser backport instead of the built-in version on both Python 2 and Python 3, simply import it explicitly as a backport:

from backports import configparser

If you’d like to use the backport on Python 2 and the built-in version on Python 3, use that invocation instead:

import configparser

For detailed documentation consult the vanilla version at

Why you’ll love configparser

Whereas almost completely compatible with its older brother, configparser sports a bunch of interesting new features:

  • full mapping protocol access (more info):

    >>> parser = ConfigParser()
    >>> parser.read_string("""
    location = upper left
    visible = yes
    editable = no
    color = blue
    title = Main Menu
    color = green
    title = Options
    >>> parser['main']['color']
    >>> parser['main']['editable']
    >>> section = parser['options']
    >>> section['title']
    >>> section['title'] = 'Options (editable: %(editable)s)'
    >>> section['title']
    'Options (editable: no)'
  • there’s now one default ConfigParser class, which basically is the old SafeConfigParser with a bunch of tweaks which make it more predictable for users. Don’t need interpolation? Simply use ConfigParser(interpolation=None), no need to use a distinct RawConfigParser anymore.

  • the parser is highly customizable upon instantiation supporting things like changing option delimiters, comment characters, the name of the DEFAULT section, the interpolation syntax, etc.

  • you can easily create your own interpolation syntax but there are two powerful implementations built-in (more info):

    • the classic %(string-like)s syntax (called BasicInterpolation)

    • a new ${buildout:like} syntax (called ExtendedInterpolation)

  • fallback values may be specified in getters (more info):

    >>> config.get('closet', 'monster',
    ...            fallback='No such things as monsters')
    'No such things as monsters'
  • ConfigParser objects can now read data directly from strings and from dictionaries. That means importing configuration from JSON or specifying default values for the whole configuration (multiple sections) is now a single line of code. Same goes for copying data from another ConfigParser instance, thanks to its mapping protocol support.

  • many smaller tweaks, updates and fixes

A few words about Unicode

configparser comes from Python 3 and as such it works well with Unicode. The library is generally cleaned up in terms of internal data storage and reading/writing files. There are a couple of incompatibilities with the old ConfigParser due to that. However, the work required to migrate is well worth it as it shows the issues that would likely come up during migration of your project to Python 3.

The design assumes that Unicode strings are used whenever possible [1]. That gives you the certainty that what’s stored in a configuration object is text. Once your configuration is read, the rest of your application doesn’t have to deal with encoding issues. All you have is text [2]. The only two phases when you should explicitly state encoding is when you either read from an external source (e.g. a file) or write back.


This backport is intended to keep 100% compatibility with the vanilla release in Python 3.2+. To help maintaining a version you want and expect, a versioning scheme is used where:

  • the first two numbers indicate the version of Python 3 from which the backport is done

  • a backport release number is provided as the final number (zero-indexed)

For example, 3.5.2 is the third backport release of the configparser library as seen in Python 3.5. Note that 3.5.2 does NOT necessarily mean this backport version is based on the standard library of Python 3.5.2.

One exception from the 100% compatibility principle is that bugs fixed before releasing another minor Python 3 bugfix version will be included in the backport releases done in the mean time.


This backport was originally authored by Łukasz Langa, the current vanilla configparser maintainer for CPython and is currently maintained by Jason R. Coombs:

Change Log


  • Issue #30: Fixed issue on Python 2.x when future is present.


  • Merge functionality from Python 3.7.2. Now ConfigParser accepts bytes paths as well as any PathLike object, including those found in the pathlib2 backport <>.


  • Issue #27: Reverted the limit on DeprecationWarning, as it had unintended consequences.


  • Issue #23: Use environment markers to indicate the ‘ordereddict’ dependency for Python 2.6.

  • Issue #24: Limit DeprecationWarning when a filename is indicated as a bytestring on Python 2. Now the warning is only emitted when py3kwarning is indicated.


  • jaraco adopts the package.

  • Moved hosting to GitHub.

  • Issue #21: Updated backports namespace package to conform with other packages sharing the namespace.


  • a complete rewrite of the backport; now single codebase working on Python 2.6 - 3.5. To use on Python 3 import from backports import configparser instead of the built-in version.

  • compatible with 3.5.1

  • fixes BitBucket issue #1: versioning non-compliant with PEP 386

  • fixes BitBucket issue #3: reload(sys); sys.setdefaultencoding('utf8') in

  • fixes BitBucket issue #5: Installing the backport on Python 3 breaks virtualenv

  • fixes BitBucket issue #6: PyPy compatibility


  • second beta of 3.5.0, not using any third-party futurization libraries


  • first beta of 3.5.0, using python-future

  • for the full feature list, see 3.5.0


  • updated the fix for #16820: parsers now preserve section order when using __setitem__ and update


  • compatible with 3.3.0 + fixes for #15803 and #16820

  • fixes BitBucket issue #4: read() properly treats a bytestring argument as a filename

  • ordereddict dependency required only for Python 2.6

  • unittest2 explicit dependency dropped. If you want to test the release, add unittest2 on your own.


  • proper Python 2.6 support

    • explicitly stated the dependency on ordereddict

    • numbered all formatting braces in strings

  • explicitly says that Python 2.5 support won’t happen (too much work necessary without abstract base classes, string formatters, the io library, etc.)

  • some healthy advertising in the README


  • a backport-specific change: for convenience and basic compatibility with the old ConfigParser, bytestrings are now accepted as section names, options and values. Those strings are still converted to Unicode for internal storage so in any case when such conversion is not possible (using the ‘ascii’ codec), UnicodeDecodeError is raised.


Conversion Process

This section is technical and should bother you only if you are wondering how this backport is produced. If the implementation details of this backport are not important for you, feel free to ignore the following content.

configparser is converted using python-future and free time. Because a fully automatic conversion was not doable, I took the following branching approach:

  • the 3.x branch holds unchanged files synchronized from the upstream CPython repository. The synchronization is currently done by manually copying the required files and stating from which CPython changeset they come from.

  • the master branch holds a version of the 3.x code with some tweaks that make it independent from libraries and constructions unavailable on 2.x. Code on this branch still must work on the corresponding Python 3.x but will also work on Python 2.6 and 2.7 (including PyPy). You can check this running the supplied unit tests with tox.

The process works like this:

  1. In the 3.x branch, run pip-run --, which downloads the latest stable release of Python and copies the relevant files from there into their new locations here and then commits those changes with a nice reference to the relevant upstream commit hash.

  2. I check for new names in __all__ and update imports in accordingly. I run the tests on Python 3. Commit.

  3. I merge the new commit to master. I run tox. Commit.

  4. If there are necessary changes, I do them now (on master). Note that the changes should be written in the syntax subset supported by Python 2.6.

  5. I run tox. If it works, I update the docs and release the new version. Otherwise, I go back to point 3. I might use pasteurize to suggest me required changes but usually I do them manually to keep resulting code in a nicer form.


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

configparser-3.7.1.tar.gz (41.4 kB view hashes)

Uploaded Source

Built Distributions

configparser-3.7.1-py3-none-any.whl (22.5 kB view hashes)

Uploaded Python 3

configparser-3.7.1-py2-none-any.whl (22.6 kB view hashes)

Uploaded Python 2

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page