IPTCInfo3 - IPTC Metadata for Python 3

About

IPTCInfo3 is a Python library for reading and modifying IPTC metadata in JPEG images. The International Press Telecommunications Council (IPTC) defines a format for exchanging meta-information in news content, including photographs. This library lets you embed and extract information like captions, keywords, copyright notices, and more.

Installation

Install IPTCInfo3 using pip or uv:

# Using pip
pip install IPTCInfo3

# Using uv (recommended)
uv pip install IPTCInfo3

Requirements: Python 3.8 or higher, no external dependencies required.

Features

🔍 Read Metadata

Extract IPTC metadata from JPEG images including keywords, captions, copyright, and more.

✏️ Modify Metadata

Add, update, or remove IPTC information in your images programmatically.

🌐 Unicode Support

Full support for international characters with proper charset handling including ISO 2022 escape sequences.

🎯 IPTC Core 1.1

Support for modern IPTC Core 1.1 fields including 'credit line' and other standard metadata.

🛡️ Safe Operations

Backup files automatically created during save operations (configurable).

⚡ Zero Dependencies

Pure Python implementation with no external dependencies required.

Quick Start

Reading IPTC Data

from iptcinfo3 import IPTCInfo

# Open an image file
info = IPTCInfo('photo.jpg')

# Read metadata
print(info['caption/abstract'])
print(info['keywords'])
print(info['copyright notice'])
print(info['by-line'])

Writing IPTC Data

from iptcinfo3 import IPTCInfo

# Open or create IPTC info (force=True for files without IPTC data)
info = IPTCInfo('photo.jpg', force=True)

# Set metadata
info['caption/abstract'] = 'A beautiful sunset over the mountains'
info['keywords'] = ['sunset', 'mountains', 'landscape']
info['copyright notice'] = '© 2024 Your Name'
info['credit line'] = 'Your Photography Studio'

# Save changes
info.save()

# Or save to a new file
info.save_as('photo_with_metadata.jpg')

Handling Different Charsets

# Specify input and output charsets
info = IPTCInfo('photo.jpg', inp_charset='utf8', out_charset='utf8')

# The library now properly handles ISO 2022 escape sequences
# including UTF-8 (ESC % G) automatically

Supported IPTC Fields

IPTCInfo3 supports all standard IPTC IIM fields. Here are some commonly used ones:

Field Name	Description	Type
`object name`	Title or name of the image	String
`caption/abstract`	Description of the image content	String
`keywords`	Searchable keywords	List
`credit line`	Credit/provider information (IPTC Core 1.1)	String
`copyright notice`	Copyright information	String
`by-line`	Creator/photographer name	String
`city`	City where photo was taken	String
`country/primary location name`	Country name	String
`destination`	Destination/transmission reference	String

See the GitHub repository for a complete list of supported fields.

What's New in v2.2.0

🐛 Bug Fixes

Fixed charset recognition for ISO 2022 escape sequences (UTF-8 as \x1b%G)
Added validation for float/NaN values to prevent TypeError during save operations
Fixed inconsistent license statements across files
Improved logging levels when force=True is used

✨ New Features

Added 'credit line' field support per IPTC Core 1.1 (backward compatible with 'credit')
Added 'destination' field as alias for compatibility with gThumb and exiftool

🚀 Build System Modernization

Migrated to modern pyproject.toml from legacy setup.py
Now uses uv and hatchling for building (PEP 517/518 compliant)
Supports Python 3.8 through 3.13

Advanced Examples

Batch Processing

import os
from iptcinfo3 import IPTCInfo

# Process all JPEG files in a directory
for filename in os.listdir('photos'):
    if filename.lower().endswith('.jpg'):
        info = IPTCInfo(f'photos/{filename}', force=True)
        info['copyright notice'] = '© 2024 Your Name'
        info['keywords'].append('batch-processed')
        info.save()
        print(f"Processed {filename}")

Avoiding Backup Files

# By default, save operations create a backup with ~ suffix
# To disable this, use the overwrite option:
info.save_as('photo.jpg', {'overwrite': True})

Working with Custom Fields

# Custom fields (custom1 through custom20) for non-standard metadata
info['custom1'] = 'Custom metadata value'
info['custom2'] = 'Another custom value'
info.save()

Resources

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Check out the Publishing Guide if you're interested in the development workflow.

License

IPTCInfo3 is dual-licensed under the Artistic License 1.0 or GNU General Public License (GPL) 1.0 or later. You may choose either license.

Original Perl version by Josh Carter, ported to Python by Tamás Gulácsi, maintained by James Campbell.