Linux: Linking Orage (XFCE4 desktop) to your Google Calendar.

To install Orage without XFCE, or with XFCE4.16 or later, see here.

What I am about to describe is a method that has worked for me on both PCLinuxOS (XFCE4 Community Edition) and MX-Linux (which uses XFCE4 by default). It ought to work on any version of Linux using the XFCE4 desktop (provided the necessary python dependencies are available — always the case as far as I know). Bear in mind, though, that there are no guarantees that it will work for you, or the sky will not fall on your head, or your computer won’t explode. You do this at your own risk.

You need to ensure that the Orage calendar is applet is on your XFCE panel. If you are using a desktop other than XFCE4, you can set Orage to appear as an icon in your system tray instead (Edit>Preferences>Extra Settings).

0: Bad News, Good News.

Just to say that the developers of XFCE4 will not be supplying Orage with the coming version (4,14) of XFCE4. It’s not been worked on for some time. That’s the bad news. The good news is that the current version should still be available for download and will still work on the XFCE4 panel. It may have to be rebuilt by your distro, though. So nag them if it disappears.

1: Install python3-pip and vdirsyncer

Firstly use your Distribution’s installer (synaptic, for example) to install the package: python3-pip. Then you need to open a terminal, either as root or precede each line with sudo, and run the following two lines in it:

pip3 install vdirsyncer
pip3 install requests_oauthlib

This will install vdirsyncer in the folder /usr/local/bin for your use.

2: Opening your Google account up to vdirsyncer

If you have already done this, then you don’t need to do it again, instead, just move the files called config and google_token (hopefully in your folder ~/.vdirsyncer/) to somewhere safe, and skip to section 3.

Otherwise, log into the Google API dashboard:

Once there click on “+ ENABLE APIS AND SERVICES” near the top of the screen.

This takes you to a search screen, and in the search box, enter “caldav”. You will get a box to click on, “CalDAV API” which you should select. You will need to Create Credentials. In return, you will get two long IDs, client_id and client_secret.

Open your File Manager, and Show Hidden Files, click into .config and create a folder within that called vdirsyncer — and inside that create a text file called config.

You should create a folder under ~/.local/share/orage/ which is your gmail address (shown as in the file that follows).

config should look like this. You will use your own gmail address, client_id and client_secret, but everything else should be typed as I have. Note that WordPress may have changed quotemarks to Left and Right quotes and doublequotes. All quotemarks should be replaced by the normal upright ones. You may just have to retype them:

status_path = "~/.vdirsyncer/status/" 

[pair mygoogle_calendar] 
a = "mygoogle_calendar_local" 
b = "mygoogle_calendar_remote" 
collections = ["from a", "from b"] 

[storage mygoogle_calendar_local] 
type = "singlefile" 
path = "~/.local/share/orage/" 

[storage mygoogle_calendar_remote] 
type = "google_calendar" 
token_file = "~/.vdirsyncer/google_token"
client_id = ""
client_secret = "1234567890abcdefghijklmnop"

Now, make a folder in your home folder (not under .config) called “./vdirsyncer”, inside that, create another folder called “status”, and inside that, another folder called “calendar”.

That’s the preparation done…

Now for the moment of truth. You need to open a terminal, and run the following command as user:

vdirsyncer discover

A browser window should pop up to complete the authorisation, and that will create an access token, another long string of characters, which you need to copy to your clipboard. Meanwhile, the terminal goes into a “waiting” state. If you click on the terminal and hit a key, you will be prompted for the access token, which you should paste in. Keep an eye on the text that outputs to the terminal, in order to know that everything has gone ok.

Finally, you can run the following command as user to download your data files from Google for the first time:

vdirsyncer sync

Now jump to Section 4.

3. IF YOU HAD vdirsyncer SET UP BEFORE

Open your File Manager, and Show Hidden Files, click into .config and create a folder within that called vdirsyncer — and inside that, copy the text files you saved earlier called config and google_token.

Edit the config file to look like that shown in Section 2, keeping lines beginning client_id and client_secret as they are, and editing the line beginning path as it looks in Section 2 but of course using your own gmail address. Other lines should be changed to match the example in Section 2 if necessary.

You should create a folder under ~/.local/share/orage/ which is your gmail address (shown as in the file in Section 2).

Now, in a terminal as user, run the following command as user to download your data files from Google.

vdirsyncer sync


When vdirsyncer sync finishes, you should have one or more files in the folder “/home/your-user-name/.local/share/orage/” which you can now link to orage.


You have to click on your panel orage time and date to bring up the calendar. You link the calendars by clicking on File>Exchange Data, and the tab called Foreign Files. Using the button “Open“, locate the folder and click on one of the ics files, with READ-ONLY clicked for now. Then click “Add”. When you have added one, try to locate some of its data both in your online Google Calendar and then by checking in Orage. There should be one calendar that you’ll want to write stuff back to. When you identify it, click on Remove, go to the “Orage File” tab, and enter it as the Orage Main Calendar File. All other files must be added in the Foreign Files tab.


In my own case, there was one I didn’t want, the main calendar in fact, which seems to add multiple copies of Birthdays, including long-forgotten ones, and loads of cruft. So I’ve excluded that from among the linked Calendars altogether. I have a separate Calendar called Diary, which I write all appointments in, and that is the Orage Main Calendar File. I have another Calendar specifically generated for Birthdays from my Google Contacts account, plus one for British Public Holidays and so on. These are READ-ONLY, on the Foreign Files tab.

5. SETTING UP vdirsyncer CRON JOB

ksnip_20200123-215739This used to involve some really weird text editors, but not any more. You can add a program called “gnome-schedule” using synaptic, though it appears in the start menu as “Scheduled tasks“. Once you’ve installed it, run it. Adding your task is simple enough. Just click on “New” and then select “A task that launches recurrently”.  You get the Dialogue box shown.

I suggest that you set the synchronisation up to run once an hour, which is the basic default. If you click on “Advanced” it’s all set up, but you can change the minute of the hour that the sync occurs, and it’s a good habit not to use the default “0”, because if you start adding more scheduled tasks, you don’t want them all going off at once! I’ve used 36. All the other settings are shown here in the dialog box. It’s best to use the full path to the command, to ensure that the command is actually found and run.


When you create a new entry using Orage, (File>New from the calendar), the entry you make is added to the Orage Default File you declared earlier. Once an hour when vdirsyncer runs, data will be merged with the copy at Google!

If, when there is also stuff to be uploaded, you do see some worrying messages if you run vdirsyncer sync in a terminal, but ignore them. It will work. Just let it run in the background on the hour!

I have updated this article and have added some screenshots, since it was originally written.

3 responses

  1. Hey so this is really awesome, I was able to get my calendar set up with Orage. I’m curious though, when I set up the foreign file, I’m getting two events for every event in my Google calendar. Do you know why this might be happening?

    1. This may be because you have your data exchange file set up as both the Orage default file and a foreign file. You shouldn’t have it set up twice. I have added an edit since your comment, which should clarify the situation.

  2. Marius Ileana | Reply

    Thank you so much for the article!

    I managed to have it working quite nice.
    I would extend a little bit the details about creating a consent screen and credentials for an ‘OAuth client ID’ in the Google Cloud.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

<span>%d</span> bloggers like this: