A vCard parser library for Java



Continuous Integration:
Code Coverage: codecov.io
Maven Central: Maven Central
Chat Room: Gitter
Q & A: Codewake
License: FreeBSD License

ez-vcard is a vCard library written in Java. It can read and write vCards in many different formats. The "ez" stands for "easy" because the goal is to create a library that's easy to use.

Downloads | Javadocs | Maven/Gradle | Documentation

String str =
"VERSION:4.0\r\n" +
"N:Doe;Jonathan;;Mr;\r\n" +
"FN:John Doe\r\n" +

VCard vcard = Ezvcard.parse(str).first();
String fullName = vcard.getFormattedName().getValue();
String lastName = vcard.getStructuredName().getFamily();
VCard vcard = new VCard();

StructuredName n = new StructuredName();

vcard.setFormattedName("John Doe");

String str = Ezvcard.write(vcard).version(VCardVersion.V4_0).go();


  • Simple, intuitive API (see Examples).
  • Streaming API.
  • Android compatibility (see ez-vcard-android project).
  • Full compliance with 2.1, 3.0, and 4.0 specifications (see Supported Specifications).
  • Supports XML, HTML, and JSON encoded vCards (see Supported Specifications).
  • Extensive unit test coverage.
  • Low Java version requirement (1.5 or above, 1.6 for jCards).
  • Few dependencies on external libraries. Dependencies can be selectively excluded based on the functionality that is needed (see Dependencies).


February 19, 2017

Version 0.10.2 released. This release adds a number of improvements and bug fixes. Please see the changelog for details.

December 31, 2016

Version 0.10.1 released. This release adds a number of improvements and bug fixes. Please see the changelog for details.

October 8, 2016

Version 0.10.0 released. This release contains mostly refactorings to support a newly integrated library. Please see the changelog for details.

Old News





compile 'com.googlecode.ez-vcard:ez-vcard:0.10.2'

Build Instructions

ez-vcard uses Maven as its build tool, and adheres to its convensions.

To build the project: mvn compile
To run the unit tests: mvn test
To build a JAR: mvn package

Eclipse users: Due to a quirk in the build process, before running the eclipse:eclipse goal, you must tweak some of the <resource> definitions in the POM file. See the comments in the POM file for details.

Questions / Feedback

You have some options:

Please submit bug reports and feature requests to the issue tracker. Contributors are listed in the project credits.


Lead Developer
Michael Angstadt

Michael Angstadt

Architecture Ideas
George El-Haddad (CardMe Project)

Maven Central Reviewer
Joel Orlina

Project Hosting
Google Code

amarnathr (hCard template bug)
bgorven (jackson-databind integration, jackson pretty printing, round-trip testing)
Moritz Bechler (Geo URI bug fix)
Kiran Kumar Bhushan (quoted-printable bug)
Sean Boylan (XXE vulnerability)
Florian Brunner (OSGi metadata)
Pratyush Chandra (ez-vcard-android)
Lívio Cipriano (Issue 35)
cmargenau (XML 1.1 support)
DerBlade (missing parameter method)
Ed Developer (wiki fix)
Juliane Dombrowski (quoted-printable line folding)
F. Gaffron (quoted-printable charsets)
isindir (Javadoc fix)
knutolav (Issue 1, Issue 2)
Nico Lehmann (Windows 10 Contacts compatibility issue)
David Nault (Issue 3, Issue 7)
rfc2822 (folding line issue, IMPP issue, trailing semicolons issue)
Steven Ruppert (folding surrogate character pairs, parsing tel URIs)
Melchin Sapir (README suggestion)
Matt Siegel (base64 property value bug, unit test bug)
David Spieler (hCard template bug)
stonio (unit test fix, readme fix)
Tom Vogel (quoted-printable charsets)
Eike Weyl (Wiki fix, Javadoc fix)
沈健 (plain-text vCard formatting issue)


Caffeine Suppliers
Volo Coffeehouse

No animals were harmed in the making of this library.