Organize and sync your calendar with khal and vdirsyncer

Keeping and sharing a calendar can be a pain. Learn how to make it easier in the fifth article in our series on 20 ways to be more productive with open source in 2020.
130 readers like this.
Poll: Upcoming open source conferences

by Dafne Cholet. CC BY-SA 2.0.


Last year, I brought you 19 days of new (to you) productivity tools for 2019. This year, I'm taking a different approach: building an environment that will allow you to be more productive in the new year, using tools you may or may not already be using.

Keep track of your schedule with khal and vdirsyncer

Calendars are a pain to deal with, and finding good tooling is always hard. But I've made some progress since last year when I listed calendaring as one of my "fails."

The most difficult thing about calendars today is that now they almost always need to be shared online in some way. The two most popular online calendars are Google Calendar and Microsoft Outlook/Exchange. Both are used heavily in corporate environments, which means my calendar has to support one or both options.

khal calendar

Khal is a console-based calendar that reads and writes VCalendar files. It's fairly easy to configure, but it does not support syncing with other applications.

Fortunately, khal works with vdirsyncer, a nifty command-line program that can synchronize online calendars (and contacts, which I'll talk about in a separate article) to your local drive. And yes, this includes uploading new events, too.


Vdirsyncer is a Python 3 program, and it can be installed via your package manager or pip. It can synchronize CalDAV, VCalendar/iCalendar, Google Calendar, and local files in a directory. Since I use Google Calendar, I'll use that as an example, although it is not the easiest thing to set up.

Setting vdirsyncer up for Google is well-documented, so I won't go into the nuts and bolts here. The important thing is to make sure your sync pairs are set up in a way that sets Google Calendar as the "winner" for conflict resolution. That is, if there are two updates to the same event, it needs to know which one takes precedence. Do so with something like this:

status_path = "~/.calendars/status"

[pair personal_sync]
a = "personal"
b = "personallocal"
collections = ["from a", "from b"]
conflict_resolution = "a wins"
metadata = ["color"]

[storage personal]
type = "google_calendar"
token_file = "~/.vdirsyncer/google_calendar_token"
client_id = "google_client_id"
client_secret = "google_client_secret"

[storage personallocal]
type = "filesystem"
path = "~/.calendars/Personal"
fileext = ".ics"

After the first sync of vdirsyncer, you will end up with a series of directories in the storage path. Each will contain several files, one for each entry in the calendar. The next step is to get them into khal. Start by running khal configure to do the initial setup.

Configuring khal

Now, running khal interactive will bring up the display shown at the beginning of this article. Typing n will bring up the New Event dialog. One small thing to note here: the calendars are named to match the directories that vdirsyncer creates, but you can change the khal config file to give them clearer names. Adding colors to entries based on which calendar they're on will also help you identify which is which on the list:

path = ~/.calendars/Personal/
color = light magenta
path = ~/.calendars/Personal/cln2stbjc4hmgrrcd5i62ua0ctp6utbg5pr2sor1dhimsp31e8n6errfctm6abj3dtmg@virtual/
color = light blue
path = ~/.calendars/Personal/c5i68sj5edpm4rrfdchm6rreehgm6t3j81jn4rrle0n7cbj3c5m6arj4c5p2sprfdtjmop9ecdnmq@virtual/
color = brown

Now when you run khal interactive, each calendar will be colored to distinguish it from the others, and when you add a new entry, it will have a more descriptive name.

Adding a new calendar entry

The setup is a little tricky, but once it's done, khal with vdirsyncer gives you an easy way to manage calendar events and keep them in sync with your online services.

What to read next

Organize your email with Notmuch

Notmuch indexes, tags, and sorts your email. Learn how to use it in the fourth article in our series on 20 ways to be more productive with open source in 2020.

User profile image.
Kevin Sonney is a technology professional, media producer, and podcaster. A Linux Sysadmin and Open Source advocate, Kevin has over 25 years in the IT industry, with over 15 years in Open Source. He currently works as an SRE at elastic.

Comments are closed.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.