How to Create a VCF File (Including By Hand)

Your contacts app exports a file and you have no idea what is inside it. When something goes wrong — a missing phone number, a name in the wrong order, a company that lost half its name — you cannot tell whether the file is broken or the app is.

A vCard is plain text. Open one in Notepad and you can read every line. Ten minutes with the format is enough to diagnose almost any contact problem yourself.

The vcf file structure, in six lines

Here is a complete, valid contact card:

BEGIN:VCARD
VERSION:3.0
FN:Ada Lovelace
N:Lovelace;Ada;;;
TEL;TYPE=CELL:+44 20 7946 0958
EMAIL:ada@example.org
END:VCARD

Save that as ada.vcf and any address book on any device will import it. That is the whole format at its simplest.

Every line follows one shape: a property name, then a colon, then the value. Some properties carry parameters after a semicolon, like TYPE=CELL.

The required vcard fields, and the two names

Only three lines are truly mandatory: BEGIN, VERSION and END. In practice you need a fourth, because a card with no name is refused by most address books.

Names are stored twice, and this confuses everyone the first time.

FN is the display name, written the way a person reads it. N is the structured version, and its five parts run family name, given name, middle names, prefix, suffix — separated by semicolons, with empty slots left in place.

That is why some apps show “Lovelace, Ada”. They sort by surname and read N, while others display FN. Writing both is the only way to get a sensible result everywhere.

Learning to write a vcard by hand

Use a plain text editor. Notepad on Windows, TextEdit in plain-text mode on a Mac, or any code editor.

Not Word. It inserts curly quotes and formatting that break parsing, and its default save format is not text at all.

Save as UTF-8. This is the setting that decides whether an accented name survives the trip to somebody else’s phone, and choosing a regional codepage instead is why names arrive full of question marks. If you need to tidy up capitalisation across a batch of names first, the case converter handles that before you build the file.

Use the .vcf ending. Windows in particular decides how to open a file from its extension.

The escaping rule that breaks more cards than anything else

Commas and semicolons mean something structural inside a value. Write them literally and the value gets cut in half.

A company called Smith, Jones & Co has to be written like this:

ORG:Smith, Jones & Co

The backslash says “this comma is text, not a separator”. Four characters need it: backslash, semicolon, comma, and newline — which is written as backslash-n rather than by pressing Enter.

We have seen this defeat plenty of generators, including an earlier version of our own. The symptom is nasty because it is silent: the file imports fine, and the company name is simply shorter than it should be. Nobody notices for weeks.

Folding long lines, and why photos need it

The specification says any line over 75 octets should be folded: broken across lines, with each continuation starting with a single space.

Octets, not characters. An accented letter is two bytes and an emoji is four, so wrapping by character count splits a symbol down the middle and produces the little replacement squares people blame on the app.

Most modern readers tolerate an unfolded line. Strict ones truncate it, and a photo generates a single line running to tens of thousands of characters, which is exactly where tolerance runs out.

Putting several contacts in one file

Stack them. Each card gets its own BEGIN and END, one after another, with no wrapper around the set.

That is what a phone export is, which is why a file named after one person often holds an entire address book. The vcf viewer counts them before you import anything.

Get a missing END line and things go wrong quietly. Some readers swallow the following card as part of the broken one, so a file of four hundred contacts imports three hundred and ninety-eight with no error message.

When to stop doing it by hand

Writing one card by hand is a genuinely useful exercise. Writing forty is a way to introduce forty chances of a missing semicolon.

The moment you have a list, use a tool. The vcard generator handles the escaping and folding for a single contact, and the CSV to VCF converter turns a spreadsheet into one file. To turn a finished card into something scannable, the vCard QR code generator encodes it without ever sending it anywhere.

Knowing the format is still what makes those tools useful, because you can read the output and check it rather than trusting it. When a card is going into a printed code, that understanding also tells you which fields to cut — keeping a card small enough to scan is mostly about knowing what each line costs.

Which version to write

Use 3.0 unless you have a reason not to. It has been understood by every address book since 2001.

Version 4.0 is cleaner: it insists on UTF-8, drops the awkward encodings, and adds properties that never existed before. It is also the one older Outlook builds and some Android contact apps still stumble over.

The differences are worth understanding before you commit a few thousand records to either, and we set them out in vCard 3.0 and 4.0 compared.