xmltodict Documentation

For very large XML files, use the streaming mode to maintain a small memory footprint. You can specify an item_depth and an item_callback function that is called whenever an element at that depth is reached.

from gzip import GzipFile
import xmltodict

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

# Parse a large gzipped XML file item by item
xmltodict.parse(GzipFile('discogs_artists.xml.gz'),
                item_depth=2, 
                item_callback=handle_artist)

You can install xmltodict using various package managers depending on your environment:

• PyPI: pip install xmltodict
• Conda: conda install -c conda-forge xmltodict
• Fedora/RHEL: sudo yum install python3-xmltodict
• Arch Linux: sudo pacman -S python-xmltodict
• Debian/Ubuntu: sudo apt install python-xmltodict
• FreeBSD: pkg install py36-xmltodict
• openSUSE/SLE: zypper in python3-xmltodict (for Python 3) or zypper in python2-xmltodict (for Python 2)

$ pip install xmltodict

To enable type checking support for xmltodict, install the external types package via PyPI or Conda:

• PyPI: pip install types-xmltodict
• Conda: conda install -c conda-forge types-xmltodict

$ pip install types-xmltodict

The force_cdata parameter in xmltodict.parse() allows you to wrap text content in CDATA sections. You can pass:

• A boolean (True to force all, False for none).
• A tuple of element names to force CDATA for specific tags.
• A callable function that accepts (path, key, value) and returns a boolean.

import xmltodict

xml = '<a><b>data1</b><c>data2</c><d>data3</d></a>'

# Force CDATA only for 'b' and 'd' elements
parsed = xmltodict.parse(xml, force_cdata=('b', 'd'))

# Use a callable for complex logic
def should_force_cdata(path, key, value):
    return key in ['b', 'd'] and len(value) > 4

parsed_complex = xmltodict.parse(xml, force_cdata=should_force_cdata)

By default, xmltodict treats namespace declarations as regular attributes. To expand namespaces, set process_namespaces=True. You can also use the namespaces argument to map specific URIs to shorthand prefixes or set a URI to None to skip it entirely.

xml = """
<root xmlns="http://defaultns.com/"
      xmlns:a="http://a.com/"
      xmlns:b="http://b.com/">
  <x>1</x>
  <a:y>2</a:y>
  <b:z>3</b:z>
</root>
"""

# Expand namespaces
parsed = xmltodict.parse(xml, process_namespaces=True)

# Collapse or skip namespaces using a mapping
namespaces = {
    'http://defaultns.com/': None, # skip
    'http://a.com/': 'ns_a',      # collapse to 'ns_a'
}
parsed_custom = xmltodict.parse(xml, process_namespaces=True, namespaces=namespaces)

Use xmltodict.parse() to convert XML strings or file-like objects into Python dictionaries. This makes XML manipulation feel like working with JSON. By default, attributes are prefixed with @ and text content uses the #text key.

import xmltodict
import json

xml_data = """
 <mydocument has="an attribute">
   <and>
     <many>elements</many>
     <many>more elements</many>
   </and>
   <plus a="complex">
     element as well
   </plus>
 </mydocument>
 """

parsed_dict = xmltodict.parse(xml_data)
print(json.dumps(parsed_dict, indent=4))

The force_list parameter in xmltodict.parse() ensures that certain elements are always returned as lists, even if they only contain a single item. This is useful for maintaining consistent data structures. You can pass:

• A boolean (True to force all, False for none).
• A tuple of element names to force lists for specific tags.
• A callable function that accepts (path, key, value) and returns a boolean.

import xmltodict

xml = '<a><b>data1</b><b>data2</b><c>data3</c></a>'

# Force lists only for 'b' elements
parsed = xmltodict.parse(xml, force_list=('b',))

# Use a callable for complex logic
def should_force_list(path, key, value):
    return key in ['b'] and isinstance(value, str)

parsed_complex = xmltodict.parse(xml, force_list=should_force_list)

When converting nested lists to XML, if a list does not have a parent key to use as a tag, xmltodict converts items to strings. To provide explicit tags for these nested items, use the expand_iter argument in unparse().

Warning: Using expand_iter breaks the ability to roundtrip the data back to the same format.

import xmltodict

# Nested list without a specific tag for items
mydict = {
    "line": {
        "points": [
            [1, 5],
            [2, 6],
        ]
    }
}

# Standard unparse (converts inner lists to strings)
print(xmltodict.unparse(mydict, pretty=True))

# Using expand_iter to provide a tag for the inner items
print(xmltodict.unparse(mydict, pretty=True, expand_iter="coord"))

Use xmltodict.unparse() to convert a dictionary back into an XML string.

• Use the attr_prefix (default @) to define attributes.
• Use the cdata_key (default #text) to define text content.
• Use pretty=True for indented, readable output.
• Note: Empty lists in a dictionary (e.g., {'a': []}) are skipped in the output. To produce an empty element, use a placeholder like {'a': ['']}.

Detailed list of arguments for xmltodict.unparse():

• input_dict: Dictionary to convert to XML.
• output=None: File-like object to write XML to; returns string if None.
• encoding='utf-8': Encoding of the output XML.
• bytes_errors='replace': Error handler used when decoding byte values.
• full_document=True: Include XML declaration if True.
• short_empty_elements=False: Use short tags for empty elements (<tag/>).
• attr_prefix='@': Prefix for dictionary keys representing attributes.
• cdata_key='#text': Key for text content in the dictionary.
• pretty=False: Pretty-print the XML output.
• indent=' ': Indentation string for pretty printing.
• newl=' ': Newline character for pretty printing.
• expand_iter=None: Tag name to use for items in nested lists (breaks roundtripping).