martinblech /xmltodict

Python module that makes working with XML feel like you are working with JSON

★ 5,759⑂ 485👁 99⑃ 167● 267▤ 6
PythonMITCreated 2012-04-17
Download: v1.0.4v1.0.4 ↓1.0.42026-02-22
+1
Daily
5,759
stars
485
forks
99
watchers
167
prs
267
issues
6
releases

README

xmltodict

xmltodict is a Python module that makes working with XML feel like you are working with JSON, as in this "spec":



python
 print(json.dumps(xmltodict.parse("""
...  
...    
...      elements
...      more elements
...    
...    
...      element as well
...    
...  
...  """), indent=4))
{
    "mydocument": {
        "@has": "an attribute",
        "and": {
            "many": [
                "elements",
                "more elements"
            ]
        },
        "plus": {
            "@a": "complex",
            "text": "element as well"
        }
    }
}


 Namespace support

By default, xmltodict does no XML namespace processing (it just treats namespace declarations as regular node attributes), but passing process_namespaces=True will make it expand namespaces for you:

python
 xml = """
... 
...   1
...   2
...   3
... 
... """
 xmltodict.parse(xml, process_namespaces=True) == {
...     'http://defaultns.com/:root': {
...         'http://defaultns.com/:x': '1',
...         'http://a.com/:y': '2',
...         'http://b.com/:z': '3',
...     }
... }
True


It also lets you collapse certain namespaces to shorthand prefixes, or skip them altogether:

python
 namespaces = {
...     'http://defaultns.com/': None,  skip this namespace
...     'http://a.com/': 'ns_a',  collapse "http://a.com/" - "ns_a"
... }
 xmltodict.parse(xml, process_namespaces=True, namespaces=namespaces) == {
...     'root': {
...         'x': '1',
...         'ns_a:y': '2',
...         'http://b.com/:z': '3',
...     },
... }
True


 Streaming mode

xmltodict is very fast (Expat-based) and has a streaming mode with a small memory footprint, suitable for big XML dumps like Discogs or Wikipedia:

python
 def handle_artist(_, artist):
...     print(artist['name'])
...     return True

 xmltodict.parse(GzipFile('discogs_artists.xml.gz'),
...     item_depth=2, item_callback=handle_artist)
A Perfect Circle
Fantômas
King Crimson
Chris Potter
...


It can also be used from the command line to pipe objects to a script like this:

python
import sys, marshal
while True:
    _, article = marshal.load(sys.stdin)
    print(article['title'])


sh
$ bunzip2 enwiki-pages-articles.xml.bz2 | xmltodict.py 2 | myscript.py
AccessibleComputing
Anarchism
AfghanistanHistory
AfghanistanGeography
AfghanistanPeople
AfghanistanCommunications
Autism
...


Or just cache the dicts so you don't have to parse that big XML file again. You do this only once:

sh
$ bunzip2 enwiki-pages-articles.xml.bz2 | xmltodict.py 2 | gzip  enwiki.dicts.gz


And you reuse the dicts with every script that needs them:

sh
$ gunzip enwiki.dicts.gz | script1.py
$ gunzip enwiki.dicts.gz | script2.py
...


 Roundtripping

You can also convert in the other direction, using the unparse() method:

python
 mydict = {
...     'response': {
...             'status': 'good',
...             'last_updated': '2014-02-16T23:10:12Z',
...     }
... }
 print(unparse(mydict, pretty=True))


	good
	2014-02-16T23:10:12Z



Te

Top issues

Latest release

v1.0.4 v1.0.4 2026-02-22
1.0.4 (2026-02-22)


 Bug Fixes

 unparse: add bytes_errors policy and handle bytes scalars consistently (ed70434)

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON