How To: Configuring Conky

As I have mentioned elsewhere, Conky is a great little application for displaying system information and other odds and ends. It’s lightweight, fast, it can be embedded on the desktop, and it’s highly customisable.

This last point could also cause a problem; Conky can afford to be so customisable because it is customised entirely through its configuration file in the home directory: ~/.conkyrc. This mass of text based commands and code might seem daunting, but it’s not too bad to configure once you get the hang of it. This guide aims to show you how.

Getting a Premade .conkyrc

To start with, many, many, many people have already posted their .conkyrc files online; you can find most of them on the Ubuntu forums here or on the Conky home page here.  If making your own Conky file seems too scary, you can always copy one of these and save it into your home directory as .conkyrc. If you like my .conkyrc (shown at the bottom of the page) I will be doing a quick and easy guide to fixing that up to a more customised look, without having to learn the meaning of every configurable option available.

Making a .conkyrc

If you do want to customise your own, it’s still good to start with the code of a look that’s similar to what you want, and then modify that. I started by using the guide that Linux Owns posted here, and expanding from that.

Two other sites you will want are from the Conky home page: the lists of Config Settings and Variables. You use the Config Settings to describe general features of how you want your Conky to appear, and the Variables to define what actually gets displayed.

Lets say we start with the basic example Conky code that comes when you install it. To find it and use it, type this:

cp /usr/share/doc/conky/examples/conkyrc.sample.gz ~/.conkyrc

The resulting conky will look like this:

The default Conky

Not very attractive, and certainly not very embedded. Lets see if we can work with that.

Open your .conkyrc in an editor of your choice. There is actually a Conky syntax Stylesheet available for Vim users, which you will find in the ‘extras’ folder of the archive, if you downloaded Conky from the website here. Just extract the archive and copy extras/vim to ~/.vim, then restart vim.

Looking at your .conkyrc, you may notice that it is divided into two sections. The first section describes your Conky appearance; default colours, location, size constraints, how it appears on the desktop (eg does it look embedded) etc. The second section is divided from the first by the line TEXT. This second section defines what information Conky will actually show, how it will be laid out, and what colours it will be in. We will look at both sections in this guide.

Section 1: Configuration Settings

The Conky website has a good list of Config Settings which make a handy reference. We’ll start by looking at Fonts. You can define a font to use using the ‘font’ option, but most people will want to use Xft, which allows you to use any font you have installed on your system. On the default .conkyrc, use_xft yes shows that Xft is already enabled. The default font is defined by xftfont and is currently set to Bitstream Vera Sans Mono:size=8. You can also set the alpha and whether the font is in Uppercase. I have MSCoreFonts installed on my system (if you’re using Ubuntu you can get this from a package called ‘Ubuntu-Restricted-Extras’). I’ve therefore chosen to set my fonts as:

xftfont comicsansms:size=8

MPD is a ‘music player daemon’ which can be used with a client to maintain and play mp3 lists over a network. Conky has the ability to display MPD music information, but unless you actually have MPD and think this would be useful, you can delete all the references to it. There are ways to display music for other players as well, and I will discuss these later.

If you use the mail spool for checking your mail, you can use mail_spool to define which it is, and see how many mails you have unread. If you use another mail client, for example gmail, don’t worry, I will also be showing a little script that allows you to show how link your gmail account to Conky.

Next we come to some of the more important settings. update_interval defines how often Conky updates its information. total_run_times defines how often it will run before it shuts down (setting this to 0 will keep Conky running permanently). Double_buffer is often necessary to eliminate flicker, but if it’s set to yes, you will have to have own_window set to yes as well. Don’t worry, you can still have the embedded appearance like this. If own_window yes is set, then set:

own_window_type override
own_window_transparent yes
own_window_hints undecorated,below,sticky,skip_taskbar,skip_pager


This will give the embedded look. You can also set own_window_colour if you don’t want the transparent look, define what colour the background should be.

Next define the location and size. alignment can be top_left, top_right, bottom_left, bottom_right or none. gap_x and gap_y define the location from the edge of the screen, and will be taken from whichever alignment has been specified. So if I have specified I want Conky to be in the bottom left of the screen, alignment_x will define how far from the left edge of the screen Conky will be displayed, and alignment_y will display how far from the bottom edge of the screen it will be. If you specify top right, then x will display how far from the right, and y will be how far from the top.

minimum_size and maximum_width are fairly self explanatory. I have found that, even with double_buffer and own_window set, there can still be some flickering, and it seems that this occurs if changing data is causing Conky to have to resize constantly. minimum_size can prevent this, if you set it to the largest size you think it is likely to have to change to. Maximum width can help you prevent Conky spreading over the width of your monitor, but if you set it too narrow, it may give a squashed appearance and make it hard for Conky to display everything it needs to.

Conky can also be set to have borders, and the appearance of these can be set with:

draw_shades
draw_outline
draw_borders
draw_graph_borders
stippled_borders
border_margin
border_width


I have shades, outline, and borders set to ‘no’, but graphs can be somewhat harder to read without defining borders, so this is set to ‘yes’ for me. You can choose how you like it. stippled_borders is set with a number that defines how stippled the border will be.

use_spacer can be useful when displaying columned lists, such as for displaying active processes and memory usage. If this is set to ‘yes’, then monotype fonts will be spaced into neat columns if there are gaps between them. It doesn’t work for truetype fonts.

You can also set the number of cpu samples that will be used to find the averages, the same for the network data, and whether or not you want to force UTF8 support.

Finally, you can define the colours. This is probably a section you will fiddle with a lot, even once you’ve got your basic Conky configuration to a setup you are happy with. All the colour settings accept hexadecimal values, but leave out the # sign, as that will just comment the number after it out, which is no good! You can also use pre-defined colour aliases, just as with html colour assignment.

default_coloris self explanatory, and you should set it to the colour you want for the majority of the text. default_shade_color will define the colour for shadows, and default_outline_color, the same for borders.

You can also define colour aliases, to use later when defining the variables conky will display. These are color1, color2 and so on to color9.

Section 2: Customising .conkyrc TEXT variables

This section is where stuff really starts to happen. There are a huge amount of variables you can choose to show for all aspects of your system’s operation. See the Conky website here for a full list. Popular choices are uptime, CPU usage, RAM usage, processes, network speed, hard drive space, you name it. If you want to show information about wireless statistics, you will need to enable this when you ./configure your Conky during install. The details on how to do this can be found on the Ubuntu forums here.

As well as using the built-in variables, you can also get Conky to display information outputted from scripts. This is more complicated, but it can be used to display information from GMail, from Amarok (or music player of your choice), information about the weather, or output from your BOINC processes. If you’re not much of a programmer yourself, don’t worry, other people have kindly posted their scripts for all of these things and more on the web, and I’ll be showing you how to take advantage of some of these.

To start with, this section is more complex than the configuration section, so lets look at some of the basics. Variables are called with the $ sign. If the variable requires options, these can be grouped using { } brackets. So for example, $color will set any text after it is called to the default colour. ${color lightgrey} specifies that the text colour should be set to lightgrey, regardless of the default colour. As with the configuration colour options, the $color variable can take any hex colour code. Unlike the configuration settings, though, hex codes need to be preceded with the # symbol.

Another important appearance variable is $font You can use this to alter fonts from the default for different parts of text. For example, to change to a monotype font for my process listings, I used:

${font bitstreamverasansmono:size=8}

Apart from the variables, text is displayed (more or less) as typed. So if you type:

This is line one.
And this is line two.

They would be shown in Conky as separate lines, just the same. If you type everything on one line, Conky will show it all as one line. This can be useful for creating strip information displays along the bottom or top of your monitor. If you leave a blank line between two lines in your Conky TEXT config, then your Conky display will have blank lines there as well. As I mentioned earlier, if you want neatly spaced columns, you will need to use a monotype font to ensure they are spaced out properly and evenly. Sections can be separated with a horizontal line, through the $hr variable. A stippled horizontal line can be created with $stippled_hr.

As you can see if you have looked at the Conky variables web-page list, there is a lot of information you can display. It probably is best to get hold of someone else’s Conky and adapt it. Once you’ve found one similar, you can cut and paste to move things around, and update the text in between the variables as you prefer. The trick is keeping track of what is where, especially with all the different colour and font variables thrown in, and it can make the code very daunting to look at. When in doubt, you can always save it, open conky to see how it looks, and then go back to it again with a fresh eye.

Although there are too many variables to go through every single one of them, I’ll look at a line of sample code from the default .conkyrc, and go through that. Hopefully, that will make the whole thing a little more comprehensible.

${color lightgrey}RAM Usage:$color $mem/$memmax - $memperc% ${membar}

The first variable defines the colour. The text RAM Usage: will appear in light grey. $color (without an argument) returns the next part of text to the default colour. The next few variables deal with displaying memory information. $mem shows the memory currently in use. / is then just a visual divider, that will display between the two values of $mem and $memmax, which displays the maximum available memory. – is just another text divider, that will display before $memperc which will show how much memory is being used as a percentage, emphasised by the text symbol %. Finally, the whole thing is finished off with a graphical bar representing memory usage – $membar. When run in Conky, this line will result in this:

RAM Usage Line

The ‘MiB’ and ‘GiB’ text is returned by the $mem and $memax with the data, and the ‘/’ divider and % symbol where part of the text specified on the line.

Another section of TEXT from the sample .conkyrc file:

${color lightgrey}Networking:
Down:${color #8844ee} ${downspeed eth0} k/s${color lightgrey} ${offset 80}Up:${color #22ccff} ${upspeed eth0} k/s
${color #0000ff}${downspeedgraph eth0 32,150 ff0000 0000ff} ${color #22ccff}${upspeedgraph eth0 32,150 0000ff ff0000}

This text produces this section of display:

Network Usage segment

The first line just produces the heading ‘Networking:’ in light grey. The second line continues in grey for the label ‘Down:’ but then switches to hex code #8844ee (purple) to display the download speed in k/s. ‘Up:’ is in light grey again, and the upload speed is displayed in hex code #22ccff (blue) in k/s. Finally, the same information is displayed as graphs with the network label, height and width, and two gradient colours as options within the curly brackets.

And Finally

There is a problem for people running Compiz, or other graphical style window managers. If Conky is set to auto-start as soon as the system boots, the Window Manager may put a shadow effect around the window frame, as it does for other programs. To prevent this, a small delay is needed on starting up. There is a special script that can be used to implement this:

#!/bin/bash
sleep 10
if pidof conky | grep [0-0] > /dev/null
then
exec killall conky
else
exec conky
fi

Save this script, for example, as conky.sh in a Scripts directory in your home folder. Set your autostart to this script, instead of directly to Conky. This script will wait a set time, before launching Conky. This should prevent any shadows.

As I hope I’ve shown, the .conkyrc is not nearly as complex as it looks, and its high customisability make it a very powerful tool.  Below is an example of just one of many looks that can be created with it.  However, if you’re still feeling confused, I will be including my own .conkyrc and a guide on how to make it less pink, later.

Conky