Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

VObject PyPI version PyPI downloads Build Status License Code Issues

VObject is intended to be a full-featured Python package for parsing and generating vCard and vCalendar files. It was originally developed in concert with the Open Source Application Foundation's Chandler project by Jeffrey Harris. Many thanks to all the contributors for their dedication and support. The project is currently being maintained by Eventable and Sameen Karim.

Currently, iCalendar files are supported and well tested. vCard 3.0 files are supported, and all data should be imported, but only a few components are understood in a sophisticated way. The Calendar Server team has added VAVAILABILITY support to VObject's iCalendar parsing. Please report bugs and issues directly on GitHub.

VObject is licensed under the Apache 2.0 license.

Useful scripts included with VObject:

  • ics_diff: order is irrelevant in iCalendar files, return a diff of meaningful changes between icalendar files
  • change_tz: Take an iCalendar file with events in the wrong timezone, change all events or just UTC events into one of the timezones PyICU supports. Requires PyICU.


To install with pip, run:

pip install vobject

Or download the package and run:

python install

VObject requires Python 2.7 or higher, along with the dateutil and six packages.

Running tests

To run all tests, use:




Creating iCalendar objects

VObject has a basic datastructure for working with iCalendar-like syntaxes. Additionally, it defines specialized behaviors for many of the commonly used iCalendar objects.

To create an object that already has a behavior defined, run:

>>> import vobject
>>> cal = vobject.newFromBehavior('vcalendar')
>>> cal.behavior
<class 'vobject.icalendar.VCalendar2_0'>

Convenience functions exist to create iCalendar and vCard objects:

>>> cal = vobject.iCalendar()
>>> cal.behavior
<class 'vobject.icalendar.VCalendar2_0'>
>>> card = vobject.vCard()
>>> card.behavior
<class 'vobject.vcard.VCard3_0'>

Once you have an object, you can use the add method to create children:

>>> cal.add('vevent')
<VEVENT| []>
>>> cal.vevent.add('summary').value = "This is a note"
>>> cal.prettyPrint()
       SUMMARY: This is a note

Note that summary is a little different from vevent, it's a ContentLine, not a Component. It can't have children, and it has a special value attribute.

ContentLines can also have parameters. They can be accessed with regular attribute names with _param appended:

>>> cal.vevent.summary.x_random_param = 'Random parameter'
>>> cal.prettyPrint()
       SUMMARY: This is a note
       params for  SUMMARY:
          X-RANDOM ['Random parameter']

There are a few things to note about this example

  • The underscore in x_random is converted to a dash (dashes are legal in iCalendar, underscores legal in Python)
  • X-RANDOM's value is a list.

If you want to access the full list of parameters, not just the first, use <paramname>_paramlist:

>>> cal.vevent.summary.x_random_paramlist
['Random parameter']
>>> cal.vevent.summary.x_random_paramlist.append('Other param')
>>> cal.vevent.summary
<SUMMARY{'X-RANDOM': ['Random parameter', 'Other param']}This is a note>

Similar to parameters, If you want to access more than just the first child of a Component, you can access the full list of children of a given name by appending _list to the attribute name:

>>> cal.add('vevent').add('summary').value = "Second VEVENT"
>>> for ev in cal.vevent_list:
...     print ev.summary.value
This is a note

The interaction between the del operator and the hiding of the underlying list is a little tricky, del cal.vevent and del cal.vevent_list both delete all vevent children:

>>> first_ev = cal.vevent
>>> del cal.vevent
>>> cal
>>> cal.vevent = first_ev

VObject understands Python's datetime module and tzinfo classes.

>>> import datetime
>>> utc = vobject.icalendar.utc
>>> start = cal.vevent.add('dtstart')
>>> start.value = datetime.datetime(2006, 2, 16, tzinfo = utc)
>>> first_ev.prettyPrint()
        DTSTART: 2006-02-16 00:00:00+00:00
        SUMMARY: This is a note
        params for  SUMMARY:
           X-RANDOM ['Random parameter', 'Other param']

Components and ContentLines have serialize methods:

>>> cal.vevent.add('uid').value = 'Sample UID'
>>> icalstream = cal.serialize()
>>> print icalstream
UID:Sample UID
SUMMARY;X-RANDOM=Random parameter,Other param:This is a note

Observe that serializing adds missing required lines like version and prodid. A random UID would be generated, too, if one didn't exist.

If dtstart's tzinfo had been something other than UTC, an appropriate vtimezone would be created for it.

Parsing iCalendar objects

To parse one top level component from an existing iCalendar stream or string, use the readOne function:

>>> parsedCal = vobject.readOne(icalstream)
>>> parsedCal.vevent.dtstart.value
datetime.datetime(2006, 2, 16, 0, 0, tzinfo=tzutc())

Similarly, readComponents is a generator yielding one top level component at a time from a stream or string.

>>> vobject.readComponents(icalstream).next().vevent.dtstart.value
datetime.datetime(2006, 2, 16, 0, 0, tzinfo=tzutc())

More examples can be found in source code doctests.


Creating vCard objects

Making vCards proceeds in much the same way. Note that the 'N' and 'FN' attributes are required.

>>> j = vobject.vCard()
>>> j.add('n')
 <N{}    >
>>> j.n.value = vobject.vcard.Name( family='Harris', given='Jeffrey' )
>>> j.add('fn')
>>> j.fn.value ='Jeffrey Harris'
>>> j.add('email')
>>> = ''
>>> = 'INTERNET'
>>> j.add('org')
>>> = ['Open Source Applications Foundation']
>>> j.prettyPrint()
    ORG: ['Open Source Applications Foundation']
    params for  EMAIL:
       TYPE ['INTERNET']
    FN: Jeffrey Harris
    N:  Jeffrey  Harris

serializing will add any required computable attributes (like 'VERSION')

>>> j.serialize()
'BEGIN:VCARD\r\nVERSION:3.0\r\nEMAIL;\r\nFN:Jeffrey Harris\r\nN:Harris;Jeffrey;;;\r\nORG:Open Source Applications Foundation\r\nEND:VCARD\r\n'
>>> j.prettyPrint()
    ORG: Open Source Applications Foundation
    VERSION: 3.0
    params for  EMAIL:
       TYPE ['INTERNET']
    FN: Jeffrey Harris
    N:  Jeffrey  Harris 

Parsing vCard objects

>>> s = """
... VERSION:3.0
... EMAIL;
... EMAIL;
... ORG:Open Source Applications Foundation
... FN:Jeffrey Harris
... N:Harris;Jeffrey;;;
... """
>>> v = vobject.readOne( s )
>>> v.prettyPrint()
    ORG: Open Source Applications Foundation
    VERSION: 3.0
    params for  EMAIL:
       TYPE [u'INTERNET']
    FN: Jeffrey Harris
    N:  Jeffrey  Harris
>>> v.email_list


A full-featured Python package for parsing and creating iCalendar and vCard files






No packages published