How to integrate Google Calendar in Linux desktop

Google Calendar is one of the most popular web applications. One can access or sync Google Calendar across multiple devices either via web interface or with native apps. In Linux, there are several ways to access Google Calendar natively, such as by using email client plugins (e.g., Evolution or Thunderbird) or calendar apps (e.g., Sunbird or Rainlendar). These solutions, however, typically involve installing unnecessarily bulky software which you will probably not need.

If all you want is to access and get reminded by Google Calendar natively on Linux, then you can consider Google Calendar command line interface (or gcalcli), which is much more light-weight. Even better for Linux desktop, you can use gcalcli together with Conky, to integrate Google Calendar into your desktop theme transparently.

In this tutorial, I will demonstrate how to integrate Google Calendar into Linux desktop, by using gcalcli and Conky.

Install gcalcli on Linux

Before installing gcalcli, verify that you are using Python 2, as gcalcli is not compatible with Python 3.

To install gcalcli on Debian, Ubuntu or Linux Mint, use the following commands.

$ sudo apt-get install git python-pip python-gdata python-dateutil python-gflags python-vobject python-parsedatetime
$ sudo pip install google-api-python-client
$ sudo pip install apiclient urllib3
$ git clone https://github.com/insanum/gcalcli.git
$ cd gcalcli
$ sudo python setup.py install

Note: gcalcli is included in the standard repository of Ubuntu or Linux mint. However, that version is not updated with the latest features and bug fixes. So I recommend building gcalcli from the source, as documented above.

To install gcalcli on Fedora, CentOS or RHEL, run the following.

$ sudo yum install git python-pip python-gdata python-dateutil python-gflags python-vobject
$ sudo pip install google-api-python-client
$ sudo pip install apiclient urllib3
$ git clone https://github.com/insanum/gcalcli.git
$ cd gcalcli
$ sudo python setup.py install

Google Authentication for gcalcli

To be able to access Google Calendar with gcalcli, you need to go through OAuth2 authention with your Google account, in order to grant gcalcli permission to access your Google Calendar.

The first time you run gcalcl, OAuth2 authentication will automatically be initiated. Thus run the following command to start.

$ gcalcli agenda

The command will print out a URL as shown below.

At the same time, it will pop up a web browser window, and direct you to the URL. If a web browser window fails to open for any reason, you can copy and paste the URL into a web browser window manually.

If you are not logged in to your Google account, you will be asked to log in. After logging in, you will see the following message, asking you to allow gcalcl to manage your Google Calendar. Click on "Accept" button.

Enable Google Calendar API

After authentication, the next step is to enable API access for Google Calendar. gcalcli accesses your Google Calendar via Google Calendar API. In order to use Google Calendar API, however, you need to explicitly enable the API under your Google account.

First go to: https://cloud.google.com/console. Click on "API Project" under project list.

Go to "APIs & auth" --> "APIs" to see a list of Google APIs. Click on toggle button for "Calendar API" to enable the API.

Now go to "APIs & auth" --> "Registered apps" to register gcalcli app. Click on "Register app" button on the top.

Fill in the app name (e.g., "My Gcalcli"), and choose "Native" as a platform. Click on "Register" button to finalize.

This will create and show OAuth client ID and secret as follows. Make a note of this information. You can ignore the warning saying that "You have not set up your product name".


The result of OAuth authentication will be saved in ~/.gcalcli_oauth text file.

Access Google Calendar from the Command Line with gcalcli

You are almost ready to access Google Calendar with gcalcli.

Create a gcalcli configuration file in your home directory as follows. Put OAuth client ID and secret that you obtained before, in the following format.

$ vi ~/.gcalclirc
--client_id='XXXXXXXXXX.apps.googleusercontent.com'
--client_secret='YYYYYYYYYYYYYYYY'

At this point, you should be able to run gcalcli from the command line.

Try the following two commands, which will print a list of your Google Calendars, and an agenda for the next 5 days, respectively.

$ gcalcli list
$ gcalcli agenda

Integrate gcalcli with Conky

The final step is to integrate the output of gcalcli into your desktop theme. For that, you need Conky, which is a very powerful tool that can display a wide range of information directly on desktop theme.

First install Conky on your Linux system.

Then, create a following script somewhere in your home directory (e.g., ~/bin).

$ vi ~/bin/gcal.sh
#!/bin/sh

gcalcli --conky calw 2 |
    sed -e 's/^[(0\x71^[(B/?/g' \
        -e 's/^[(0\x78^[(B/?/g' \
        -e 's/^[(0\x6A^[(B/?/g' \
        -e 's/^[(0\x6B^[(B/?/g' \
        -e 's/^[(0\x6C^[(B/?/g' \
        -e 's/^[(0\x6D^[(B/?/g' \
        -e 's/^[(0\x6E^[(B/?/g' \
        -e 's/^[(0\x74^[(B/?/g' \
        -e 's/^[(0\x75^[(B/?/g' \
        -e 's/^[(0\x76^[(B/?/g' \
        -e 's/^[(0\x77^[(B/?/g'
$ chmod +x ~/bin/gcal.sh

Important Note: '^[' in the above script must be the actual ESCAPE key (i.e. press Ctrl-V ESC in vi editor).

This script translates VT100 escape sequences to Unicode box drawing characters. This is a needed workaround because Conky does not support ASCII line art used by gcalcli.

Finally, create a Conky configuration file in your home directory as follows.

$ vi ~/.conkyrc
alignment top_right
maximum_width 630
minimum_size 330 10
gap_x 25
gap_y 50

own_window yes
own_window_type conky
own_window_hints undecorated,below,sticky,skip_taskbar,skip_pager
own_window_transparent yes
own_window_argb_visual yes
own_window_argb_value 0

update_interval 300
background no

border_width 1
default_color cornflowerblue
default_outline_color white
default_shade_color white
double_buffer no
draw_borders no
draw_graph_borders no
draw_outline no
draw_shades no
max_port_monitor_connections 64
max_specials 512
max_user_text 16384
text_buffer_size 8096
no_buffers yes
out_to_console no
uppercase no
use_xft yes
xftfont Bitstream Vera Sans Mono:size=10

TEXT
*** Google Calendar Agenda ***
${execpi 300 gcalcli --conky agenda}
${execpi 300 ~/bin/gcal.sh}

This Conky configuration will display an agenda and two weeks' worth of schedules of your Google Calendar, directly in your desktop theme. The displayed info is updated every 5 minutes.

Now you can activate Conky by running the following.

$ conky

You should see Google Calendar in the right side of your Linux desktop as follows.

Once you verify that Google Calendar shows up correctly, you can set Conky to auto-start every time you log in to your desktop.

Set up Google Calendar Reminder

gcalcli can also send a reminder for any upcoming schedule in your Google Calendar. It uses notify-send command to send desktop notifications. For Google Calendar reminder, you can set up a cron job like the following.

$ crontab -l
*/10 * * * * /usr/local/bin/gcalcli remind

Subscribe to Xmodulo

Do you want to receive Linux FAQs, detailed tutorials and tips published at Xmodulo? Enter your email address below, and we will deliver our Linux posts straight to your email box, for free. Delivery powered by Google Feedburner.

37 thoughts on “How to integrate Google Calendar in Linux desktop

  1. Just use KDE Plasma and Akonadi. Google Calendar/Contacts and Task are very well integrated (there are widgets for the desktop aka plasmoids and the PIM application Kontact). There is no need to install unnecessary software ;-)

  2. Nice! Conky is new to me since I've switched to Crunchbang. This puts me one step closer to jumping permanently out the window(s).

  3. I followed your steps for installing, but when running the "gcalcli agenda" step, I get the following:

    "ERROR: Missing module - cannot import name __version__"

    Not sure what I"m missing here. Running Ubuntu 13.10 64bit

  4. Rather than the convoluted sed parsing, you should be able to just specify "--nolineart" or "--lineart=0" on the command line (at least in recent versions available from github, since about Feb of 2013) which should use regular ASCII characters rather than fancy visual display characters. The older version on Debian Stable doesn't seem to offer this though. YMMV.

      • Instead of running
        gcalcli --conky calw 2 | sed …
        you'd just run
        gcalcli --nolineart --conky calw 2

        • ${execpi 300 gcalcli --nolineart --conky calw 1 agenda}

          I get - error: Failed to parse start time

          Also I've been trying to work out getting the time to be displayed correctly. It's currently 7 hours a head of what it should be.

  5. I don't understand why do you want to integrate it to desktop. I use Thunderbird, and Google calendar integrates with it at least in two ways: Google calendar provider and Lightning. Works fine.

  6. Interesting proof of concept and quite useful too. I just guess I don't have the same patience to go through all the steps at this stage of my life and prefer the bulky software. :)

  7. Hello,
    When I try to Enable Google Calendar API by clicking on the link "https://cloud.google.com/console" I have no project list and no "API Project" option. I have a option to creat a new project but I don't know how to creat one!
    What I should do?
    Thanks!

    • Staggering: I had the same issue. I created an API project, which got me a few more steps down the road, but I did not get the ability to register an app. Just: APIs | Credentials | Consent screen | Push as options under APIs and Auth.

      I selected all of them and none of them looked right. So I am likely stuck, but I do have a few more things to click just for fun.

      • Google changed their interface. All the stuff is there, just different. -sigh-

        + Create a new project.
        + Add the Calendar API
        + Under API&Auth click on 'Credentials'
        + Click 'Create New Client ID'
        + Click 'Installed Application' type 'Other'

        You will then have a Client ID and Client Secret associated with a native application.
        Proceed as above.

        HTH .. mark.

        • Thanks mark5009 I was proceeding through guess work so your tips really helped. Got it now running using Crunchbang Waldorf. Would love to alter those ghastly colours back to something more Crunchbang subtle, but it's definitely a great starting point.

          I was attempting to integrate using Icedove and Lightning. Just for a calendar. Seemed way too bloated so this guide and the amazing help through the comments got me there.

  8. I am stuck at the Google Api step. When I go to the link adress what I see is categories: 1. Projects 2. Billings 3. Account settings and I can only create my own project. I cannot find any API. I tried switching to 'original console' and it mantions about APIs access but there are no options like on your screenshot. Am I doing something wrong or it was Google who changed the content of the site?

  9. Awesome guide! However, rather than using Conky to display a calendar, I made a web application using Midori for Google Calendar. One could use Firefox/Chrome/Fogger to achieve the same affect, though. I am using a web application rather than an actual calendar application simply because, with the exception of Thunderbird (which is a bit too heavy for me), there are no applications that are GTK and Gnome-Free that can synchronize with calendar...If there are, do let me know! :)

  10. I tried the procedures to integrate google calendar in linux desktop. At some time I was going to authenticate with google I decided to continue and complete this the next day. Now the terminal does not respond. I have no way of getting this to work. Any suggestions?

  11. I had the same results as Filip on April 8, 2014 at 12:19 am

    I did step 1 below, but I was unable to proceed with step 2, exactly as Filip describes.
    + Create a new project.
    + Add the Calendar API

    I created two projects, I don't know if that was necessary or not. What I found, is that it took a few minutes, but the screen finally updated. I was then able to choose "Enable an API"... from there a list of dozens of API's appeared. I scrolled down and the Calendar API was in the list. I clicked on the button that said "Off" and changed it to "On".

    From there I was able to proceed, I didn't know exactly where to continue from since the directions require that I bounce back and forth between the original post and the comments, but I took a wild guess that I'm supposed to start from vi ~/.gcalclirc. I continued from there, but I should mention that I also needed to "mkdir ~/bin" before I could create ~/bin/gcal.sh

    I all the way through starting conky, but I got this:
    Conky: /home/apb/.conkyrc: 8: config file error
    Conky: desktop window (1c001b7) is subwindow of root window (158)
    Conky: window type - normal
    Conky: drawing to created window (0x5800002)
    Conky: drawing to single buffer
    and then it just sits.
    Line 8 is: "own_window_type conky"

    I incorporated all comments. After waiting a while, I can say it works! Only problem now are the colors. I see where the cornflowerblue gets set, but what about the yellow and red? Colors look great on your black background, but I have a white background (which I prefer).

    Other than that, thanks for the awesome tutorial (would be nice if you rewrote it to incorporate the needed changes as set forth in the comments, as I had to incorporate all of them and it made my brain hurt).

Leave a comment

Your email address will not be published. Required fields are marked *

Current day month ye@r *