Blurred background of programming code with a multi colored address book in the foreground

Converting Address Book Contacts from vCard

  • Adam Douglas
  • app

One day I was presented with a problem of taking contacts exported to vCard file format from an old iMac computer and then importing into Mozilla Thunderbird on Linux. It sounded simple, but for some reason the import into Thunderbird will fail without an explanation. Quickly I started searching for a simple vCard validator, but unfortunately came up empty. So I switched to looking into how to convert the vCard v2.1 file of over 1,300 contacts to an LDIF (LDAP Data Interchange Format) or even CSV (common-separated values) file format in hopes it would resolve the import problem.

Danger

Using online services to convert a contact file is strongly discouraged for privacy reasons. Such services quite often scrape (copy) the data for their own use.

What is a vCard?

A standard electronic file format for business cards that is also known as virtual contact file (vcf). Each card can contain such data as anniversary date, birthday date, email addresses, phone numbers, photograph, etc.

Environment

  • Arch Linux
  • Git v2.37.1
  • Nginx v1.22.0
  • PHP-FPM v8.1.8

Assumptions

  • Steps prefixed with a “$” (dollar sign) represents the CLI (command-line interface) prompt
  • Steps prefixed with a “#” (number sign) represents the CLI prompt with elevated user permissions (e.g. root)
  • The text after the “$” or “#” is to be entered at the CLI
  • Nginx, PHP-FPM and git is already installed and configured

Problem

When attempting to import the vCard file using Mozilla Thunderbird, the import fails with a message of “An error occurred importing addresses from vCard file (.vcf). Error importing address book adamsdesk, all address may not have been imported.” Refer to screenshot below.

After the import I looked in the address book and saw a new address book called “adamsdesk”. Within this address book there was only 2 contacts out of 1,392. Those 2 contacts were primarily empty.

Mozilla Thunderbird vCard import error dialog

Solution - Vcfconvert

I decided to install a local copy of Vcfconvert so I can avoid potentially exposing private data.

Note

It is assumed that the installation and configuration of web server software has been done prior to installing Vcfconvert.

  1. Change directory.
    $ cd /srv/http
    
  2. Git clone project.
    # git clone https://github.com/thomascube/vcfconvert
    
  3. Create Nginx site configuration.
    # nano /etc/nginx/sites-available/vcfconvert.conf
    
    server {
     listen 80 default_server;
     listen [::]:80 default_server ipv6only=on;
     server_name _;
    
     root /srv/http/vcfconvert;
     index index.php index.html;
    
     access_log /var/log/nginx/vcfconvert_access.log;
     error_log /var/log/nginx/vcfconvert_error.log;
    
     location ~ \.php$ {
         try_files $uri =404;
         fastcgi_split_path_info ^(.+\.php)(/.+)$;
         fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
         fastcgi_index index.php;
         fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
         include fastcgi_params;
     }
    }
    
  4. Start Nginx and php-fpm.
    # systemctl start nginx.service php-fpm.service
    
  5. Open http://127.0.0.1 in a web browser and following on screen instructions.

After I converted the vCard to an LDIF file format I was successfully able to import the contacts into Mozilla Thunderbird.

Resources

Here are some alternate resources I found for conversion tools.

  • contacts2vcard

    An Android contacts (contacts2.db) to vCard format converter.

  • csvTovcf

    A Python script that parses a .csv file of contacts and automatically creates vCards.

  • node-vcf

    A not so forgiving vCard / vcf parser

  • varc2to3

    Convert vcards from version 2.1 to version 3.0

  • vCard module

    vCard 3 validator, class and utility functions

  • vCard PHP library

    This vCard PHP library can easily parse or generate/export vCards as .vcf.

  • vCard Splitter & Merger
  • vCard to CSV
  • vcardtools

    Automatically fix, convert, split, normalize, group, merge, deduplicate vCard and VCF files (even large ones). Imports vCard v2.1 and v3.0. Outputs vCard v3.0.