All articles

How Do I Add a Photo to a vCard?

To add a photo to a vCard, set it in your contacts app and export with photos on, or embed a small JPEG as Base64 in the PHOTO line. Links rarely work.

Cover reading How Do I Add a Photo to a vCard? on a dark background

To add a photo to a vCard, set the picture on the contact in your contacts app and export the card with photos switched on. If you are building the file yourself, add a PHOTO line with a small JPEG encoded as Base64. A PHOTO line that only links to an image is allowed by the standard, but phones often ignore it.

What are the ways to add a photo to a vCard?

There are three ways to add a photo to a vCard: let a contacts app write it, embed the image data by hand, or link to an image on the web. Only the first two are dependable.

Method Effort Does the photo show up?
Export from a contacts app with photos on Low Yes, the app embeds it for you
Embed Base64 data in the PHOTO line Medium Yes, if the line is written correctly
Link to an image URL in the PHOTO line Low Often not, especially on iPhone

This primer on what a vCard file is explains the lines you will see below.

How do I add a photo to a vCard on a Mac?

On a Mac, add the photo to the contact in the Contacts app, turn on “Export photos in vCards”, then export. The app writes the PHOTO line for you.

  1. Open Contacts, select the person, click Edit and add the picture.
  2. Choose Contacts > Settings, then click vCard.
  3. Tick Export photos in vCards. Apple describes it as including your contacts’ images when you export contacts as vCards.
  4. Leave vCard Format alone unless you have a reason. The default format is 3.0.
  5. Select the contact and choose File > Export > Export vCard, pick a location and click Save.

Apple’s export guide says you can exclude photos and notes from a .vcf, so a file exported with the box off has no picture in it at all.

On an iPhone, put the photo on the contact first, then follow this guide to exporting iPhone contacts as a VCF file.

How do I embed a photo in a vCard file by hand?

To embed a photo by hand, convert a small JPEG to Base64 text and paste it into a PHOTO line. The exact wording of that line depends on the vCard version at the top of the file.

vCard 3.0. The 3.0 specification says the encoding “MUST be reset to “b”“ for inline binary data, and the TYPE must name the image format. A complete file looks like this:

BEGIN:VCARD
VERSION:3.0
N:Nair;Priya;;;
FN:Priya Nair
EMAIL:priya@example.com
PHOTO;ENCODING=b;TYPE=JPEG:/9j/4AAQSkZJRgABAQAAAQABAAD...
END:VCARD

vCard 4.0. The 4.0 specification changes the rule: the PHOTO value is “a single URI”. To embed, use a data: URI.

PHOTO:data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...

The steps:

  1. Crop the picture to a square and save it as a small JPEG. Base64 makes the data about a third bigger, so a large photo produces a huge file.
  2. Convert it. On a Mac, run base64 -i photo.jpg in Terminal. On Windows, run [Convert]::ToBase64String([IO.File]::ReadAllBytes("photo.jpg")) in PowerShell.
  3. Open the .vcf in a plain text editor. Check the VERSION line.
  4. Add the PHOTO line for that version above END:VCARD and paste the Base64 after the colon.
  5. Save with the .vcf extension, not .txt.

The standard says content lines “SHOULD be folded to a maximum width of 75 octets”. A Base64 photo is one very long line, so apps that follow the rule split it across many short lines. If you paste by hand, keep it as one unbroken line or fold it properly. A stray line break in the middle cuts the image off.

Does a photo URL work instead of embedded data?

A photo URL is valid vCard, but it rarely displays. Both specifications allow a link, and real phones mostly do not fetch it.

Version 3.0 lets you write PHOTO;VALUE=uri: followed by a web address, and 4.0 lets you put the address straight after PHOTO:.

Developers have been asking Apple about this since 2020. The forum thread opens with the observation that “the only format accepted for the PHOTO field is Base64”. Later replies report the same result. The most recent one, from December 2024, just asks whether it still doesn’t work. No Apple engineer has answered, so this is user testing, not official policy.

My view: never use the link form. It saves a few kilobytes and costs you the photo on the phone most likely to open your card.

Can a vCard QR code carry a photo?

No, not reliably. An embedded photo is too much data for a QR code, and a linked photo gets ignored.

A designer documented this in 2023 while building a vCard 3.0 QR code. The Base64 text was “too long” for the QR generator. The linked form did not work on Android or iOS across the four phones she tested. One reply summed it up: few, if any, native QR readers process PHOTO info.

The workaround is to keep the contact out of the code. Encode a link to a page, and let that page hand over the .vcf file. This comparison of static and link-based vCard QR codes shows how the two differ.

QRCard takes the link route. Your QR code and URL point to a live profile, and its Save Contact button generates a vCard 3.0 file that opens in the phone’s own Contacts app. You can see the flow on the features page.

How do I check that the photo worked?

Send the file to yourself and open it on a phone before you share it. The preview screen shows the photo before you save anything.

Test on both an iPhone and an Android phone if you can. When the picture is missing, check these in order:

  • Version mismatch. A 3.0 file needs ENCODING=b. A 4.0 file needs the data: URI.
  • Broken Base64. Look for a blank line or a cut-off ending.
  • Photos turned off at export. Open the file in a text editor and search for PHOTO. If it isn’t there, re-export.

If the whole card fails to open, that is a different problem, covered in why a vCard won’t import on iPhone.

One limitation: I can’t tell you how every contacts app treats a photo on import. Google’s export help, for example, says you can download contacts as a CSV or vCard file and never mentions photos. Test with the apps your contacts use.

The picture will sit in someone’s address book for years. These notes on choosing a profile photo for a business card apply here too.

FAQ

What is the PHOTO line in a vCard?

PHOTO is the vCard property that carries a picture of the person or company. In vCard 3.0 it holds Base64 image data or a URI. In vCard 4.0 its value is always a single URI, which can be a data: URI with the image inside.

Why is my vCard photo not showing on iPhone?

The most common cause is a PHOTO line that links to a web address. Developers on Apple’s forum report that iPhone only accepts a Base64 photo and ignores linked ones. Embed the image instead.

Can I add a photo to a vCard in a text editor?

Yes. Convert a small JPEG to Base64 and paste it after PHOTO;ENCODING=b;TYPE=JPEG: in a vCard 3.0 file. It works, but the line runs to thousands of characters, so exporting from a contacts app is easier.

Can a vCard QR code include a photo?

Not in practice. An embedded photo is far too much data for a QR code, and people who tested linked photos found phones ignored them. Point the QR code at a profile page that shows your photo instead.

Should the photo be embedded or linked?

Embedded. The vCard specifications allow both, but a linked photo depends on the receiving app fetching it, and reports from iPhone and Android users say it often does not.

Sources