Install & Compatibility
Where this runs
tested against v0.9.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.074s · 21.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.066s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
readOne
✓ vobject.readOne(...)
Used to parse a single vCard or iCalendar component from a string or stream.
readComponents
✓ vobject.readComponents(...)
Used to parse multiple vCard or iCalendar components from a string or stream, returning an iterator.
newFromBehavior
✓ vobject.newFromBehavior('vcalendar')
Creates a new vobject component with a specific behavior (e.g., 'vcalendar', 'vevent', 'vcard').
iCalendar
✓ vobject.iCalendar()
Convenience function for creating a new VCALENDAR object.
vCard
✓ vobject.vCard()
Convenience function for creating a new VCARD object.
This quickstart demonstrates how to create a basic iCalendar event, add properties including datetime objects, and then serialize it into an iCalendar string. It also shows how to parse a vCard string using `vobject.readOne()` and access its properties. Note that `vobject` automatically adds mandatory components like `UID` and `DTSTAMP` during serialization if they are not explicitly set.
import vobject
import datetime
# Create a new iCalendar object
cal = vobject.iCalendar()
# Add an event component
event = cal.add('vevent')
# Add properties to the event
event.add('summary').value = 'Meeting with AI team'
event.add('dtstart').value = datetime.datetime(2026, 4, 15, 10, 0, 0, tzinfo=datetime.timezone.utc)
event.add('dtend').value = datetime.datetime(2026, 4, 15, 11, 0, 0, tzinfo=datetime.timezone.utc)
# Print the iCalendar object in a human-readable format
print('--- Pretty Print ---')
print(cal.prettyPrint())
# Serialize the iCalendar object to its string representation
# vobject will automatically add missing mandatory properties like UID and DTSTAMP
ical_string = cal.serialize()
print('\n--- Serialized iCalendar ---')
print(ical_string)
# Example of parsing a vCard from a string
vcard_string = """
BEGIN:VCARD
VERSION:3.0
N:Doe;John;;;
FN:John Doe
EMAIL;TYPE=WORK:john.doe@example.com
END:VCARD
"""
try:
parsed_vcard = vobject.readOne(vcard_string)
print('\n--- Parsed vCard (FN) ---')
print(parsed_vcard.fn.value)
except Exception as e:
print(f"Error parsing vCard: {e}")
Debug
Known issues
breakingThe `vobject` library has two main series: 0.9.x and 1.x. Version 0.9.x (including the current 0.9.9) maintains compatibility with Python 2.7 and earlier Python 3 versions. The upcoming 1.x series will *only* support Python 3.8 and later. Be aware of this when planning Python environment upgrades or starting new projects.fixFor new projects or Python 3.8+, consider waiting for the 1.x series or explicitly targeting 0.9.x if Python 2.7 compatibility is required. Check the official documentation for the latest guidance on the 1.x release.
affects: All versions, especially when migrating across major Python versions.
gotchaWhen parsing iCalendar or vCard strings, `vobject.readOne()` and `vobject.readComponents()` expect well-formed input, including closing `END:` tags for all components. Missing `END:` tags or malformed input will result in parsing errors (e.g., `SyntaxError` or `StopIteration`).fixEnsure input strings are complete and correctly formatted. Use triple quotes for multi-line strings in Python code to preserve line feeds. When processing external data, consider pre-validation or robust error handling around parsing calls.
affects: All versions
gotchaAccessing properties directly via `item.contents['property_name']` will return a list, even if only one value exists for that property. You often need to access `item.contents['property_name'][0].value` to get the actual value. Convenience attributes like `item.summary.value` or `item.dtstart.value` are available for common, single-value properties.fixFor single-value properties, prefer direct attribute access (e.g., `component.dtstart.value`). For potentially multi-value properties or when inspecting the raw structure, be mindful that `item.contents` returns lists and iterate or access by index accordingly.
affects: All versions
gotchaDuring serialization (`.serialize()`), `vobject` automatically adds mandatory iCalendar/vCard properties like `UID`, `DTSTAMP`, and `PRODID` if they are not already present. While usually beneficial for creating valid files, this can be unexpected if strict control over all output properties is desired before serialization.fixIf specific values for mandatory properties are required, ensure they are explicitly added to the vobject component before calling `.serialize()`.
affects: All versions
deprecatedUsers running `vobject` on Python 3.9+ may encounter `DeprecationWarning: invalid escape sequence` messages, primarily originating from internal regular expressions in `vobject/base.py`. These are warnings and do not stop execution but indicate potential future compatibility issues or a need for updated regex patterns.fixThese are generally benign warnings for now. Keep `vobject` updated to its latest versions, as these might be addressed in future releases, particularly in the 1.x series targeting newer Python versions.
affects: 0.9.x on Python 3.9+
Upgrade
Version history
0.9.9latest on PyPI · released Dec 16, 2024
Audit
Dependencies
python-dateutilrequiredRequired for date and time parsing/serialization, including recurrence rules.
sixrequiredPython 2/3 compatibility layer, required for the 0.9.x series.
pyicuoptionalRequired by the 'change_tz' script for advanced timezone conversions; not needed for core library functionality.