Casey's Conky Reference with Examples

conky --version

conky --quiet

conky --debug

conky --alignment=top_right

conky --double-buffer

The default configuration file location is $HOME/.config/conky/conky.conf or ${sysconfdir}/conky/conky.conf On most systems, sysconfdir is /etc, and you can find the sample config file there (/etc/conky/conky.conf).

conky -c conkyrc.conf

conky --print-config

conky --daemonize

conky -f Ubuntu

conky --help

conky --own-window

conky --for-scripts 'Your uptime is: $uptime'
conky -s 'Your uptime is: $uptime'

cat conkyrc.conf | conky --stdin-config

conky --text=' $uptime '
conky -t ' $uptime '

conky --pause=10
conky -p 10

conky --interval=2
conky -u 2

conky -w 4101

conky --display=2

conky -x 150

conky -y 20

conky -i 300

#alignment top_left
alignment top_right
#alignment bottom_left
#alignment bottom_right
#alignment none

append_file /home/user/.config/conky/common.conf

background yes

border_inner_margin 0

border_outer_margin 0

border_width 0

color8 995500
TEXT
${color8}

cpu_avg_samples 2

default_bar_size 0 6

default_color AAAAAA

default_gauge_size 25 25

default_graph_size 0 25

default_outline_color green

default_shade_color red

disable_auto_reload yes

diskio_avg_samples 2

display 1

double_buffer yes

draw_borders no

draw_graph_borders yes

draw_outline yes

draw_shades yes

extra_newline no

1. Font Name - The name of the font as it appears in your system. The xfontsel program can be used to find a nice font installed on your system.
2. [size=] - [optional] The desired size of the font in pixels.
3. [weight] - [optional] The font weight. For example: bold, normal

font Ubuntu:size=11:bold

format_human_readable yes

gap_x 10

gap_y 10

hddtemp_host 127.0.0.1

hddtemp_port 7634

• up = the interface is connected
• link = the interface has a link (to hub, switch, modem, etc.)
• address = the interface has an assigned IP address

if_up_strictness address

imap mailserver.example.com user password -i 60 -f "home" -r 5

# Update image every 5 minutes
imlib_cache_flush_interval 300

imlib_cache_size 4096

mail_spool $MAIL

max_port_monitor_connections 256

max_specials 512

max_text_width 0

max_user_text 16384

maximum_width 200

maximum_size 400

mpd_host 127.0.0.1

mpd_password pass

mpd_port 6600

music_player_interval 1

net_avg_samples 2

no_buffers yes

nvidia true

out_to_console no

out_to_ncurses no

out_to_stderr no

out_to_x yes

override_utf8_locale yes

overwrite_file ~/example.log

own_window yes

own_window_class Conky

own_window_colour 000000

If you use own_window_type override window manager hints have no meaning and are ignored.

own_window_type desktop
own_window_type override

own_window_title Conky

own_window_argb_visual no

own_window_argb_value 128

own_window_transparent yes

#own_window_type normal
#own_window_type desktop
#own_window_type dock
#own_window_type panel
own_window_type override

pad_percents 2

pop3 pop3.example.com user password -i 300 -p 110 -r 5

short_units yes

show_graph_range yes

show_graph_scale yes

stippled_borders 2

temperature_unit celsius
#temperature_unit fahrenheit

• \n = New line. This allows the one line template to expand to multiline output.
• \\ = A single backslash character.
• \ = A space character (quotes used to show trailing space). Variables with spaces must use the backslash before each space character.
• \N = Template argument N (e.g. \1, \2, \3, \4, \5, \6, \7, \8, \9)

template0 ${\1\2}
template1 \1: ${fs_used \2} / ${fs_size \2}
template2 \1 \2

TEXT

The following lines show what each template expands to.
${template0 node name} = ${nodename}

${template1 root /} = root: ${fs_used /} / ${fs_size /}

You can even pass one template to another template.
${template1 ${template2\ disk\ root} /} = disk root: ${fs_used /} / ${fs_size /}

text_buffer_size 256

times_in_seconds yes

top_cpu_separate no

top_name_width 20

total_run_times 0

update_interval 0.5

update_interval_on_battery 5

uppercase no

#use_spacer left
use_spacer right
#use_spacer none

use_xft yes

xftalpha 0.7

xftfont Ubuntu

The following list of variables can be used in the TEXT block.

# Tell Conky to run 10 times then exit.
total_run_times 10
# Update Conky display (in seconds) when on AC power.
update_interval 2

TEXT
Conky ${Conky_version}

[interface]

${addr eth0}

[interface]

${addrs eth0}

[number]

${alignc -5}

[number]

${alignr 2}

text_and_other_conky_vars

${blink "Warning: ${battery_percent BAT1} depleted!"}

${buffers}

${cached}

"string"

${cmdline_to_pid "demo"}

[color]

${color red}This is Red
${color green}This is Green
${color blue}This is Blue
${color #FFA500}This is Orange

color8 f9cc00
TEXT
${color8}

var1 var2

${combine ${head /proc/cpuinfo 2} - ${head /proc/meminfo 1}}

url [interval_in_minutes]

${curl http://www.ifxgroup.net/conky.htm 1440}

[network_interface]

${downspeed eth0}

[network_interface]

${downspeedf eth0}

[network_interface] [height][,width] [gradient color 1] [gradient color 2] [scale] [-t] [-l]

${downspeedgraph eth0 20,120 -t -l}

[mail_directory]

${if_existing ~/example.log}
${else}
${endif}

${if_existing ~/example.log}
${else}
${endif}

"string"

${eval "Local time is $${time %a, %d %b %Y %T %z}"}

api_userid api_key character_id

[mail_directory]

[font][:weight][:size]

${font Ubuntu:bold:size=12}

seconds format

• \w = Weeks
• \d = Days
• \h = Hours
• \m = Minutes
• \s = Seconds
• \( = Open parens
• \) = Close parens
• \\ = Single backslash
• () = Text between paren characters is not visible if a replaced unit in the text is 0.
• \S# = Show the numbers behind the point if seconds is a decimal number. # is a number of digits behind the point to show. Maximum is 9. Use x (eg. \Sx) to show all digits behind the point with no trailing zeros up to a maximum of 9 digits.

${format_time "\h:\m:\s"}

[mail_directory]

[cpu_number]

${freq}MHz

[cpu_number]

${freq_g}Ghz

number

${goto 10}

${gw_iface}

${gw_ip}

[device]

${hddtemp}

logfile lines [next_check]

${head ~/sample.log 5 3}

[height]

${hr 1}

[device] type n [factor offset]

• in = Voltage (same as vol)
• vol = Voltage (same as in)
• fan = Fan speed
• temp = System temperature

${hwmon temp 1}°C

[device] type n [factor offset]

codeset_from codeset_to

${iconv_start UTF-8 ISO_8859-1}
${iconv_stop}

${iconv_start UTF-8 ISO_8859-1}
${iconv_stop}

<path to image> [-p x,y] [-s WxH] [-n] [-f interval]

${image ~/cheeseburger.jpg -p 20,20 -s 200x200 -f 300}

host username password [-i interval (in seconds)] [-f "folder"] [-p port] [-e "command"] [-r retries]

• host = The URL of the IMAP mail server
• username = The username to access the account
• password = Use * for Conky to prompt for the password.
• -i interval = Poll frequency in seconds. Default is 300 (5 minutes)
• -f "folder" = Default folder is INBOX
• -p port = Default port is 143
• -e "command" = Optional IMAP command to send.
• -r retries = Default is 5 before giving up.

${imap_messages imap.example.com user *}

host username password [-i interval (in seconds)] [-f "folder"] [-p port] [-e "command"] [-r retries]

• host = The URL of the IMAP mail server
• username = The username to access the account
• password = Use * for Conky to prompt for the password.
• -i interval = Poll frequency in seconds. Default is 300 (5 minutes)
• -f "folder" = Default folder is INBOX
• -p port = Default port is 143
• -e "command" = Optional IMAP command to send.
• -r retries = Default is 5 before giving up.

${imap_unseen imap.example.com user *}

filename

${include /etc/conky/common.cfg}

disk

${ioscheduler sda}

${kernel}

${laptop_mode}

textfile

${lines ~/example.txt}

[1|2|3]

${loadavg 1}

[height][,width] [gradient color 1] [gradient color 2] [scale] [-t] [-l]

${loadgraph 20,120 888888 FFFFFF -l}

${machine}

[mailbox]

[-n #] [-fw #] [-sw #] mbox

• -n # = number of message to show
• -fw # = width in characters of FROM field
• -sw # = width in characters of SUBJECT field
• mbox = filename of the mailbox enclosed in double quotes (")

${mboxscan -n 10 "/home/user/some box"}

${monitor}

${monitor_number}

[index]

${nameserver 0}

[mailbox]

${nodename}

${nodename_short}

item

• threshold - The threshold temperature at which the GPU slows down
• temp - Gives the GPU current temperature
• ambient - Gives current air temperature near GPU case
• gpufreq - Gives the current GPU frequency
• memfreq - Gives the current memory frequency
• imagequality - Which image quality should be chosen by OpenGL applications

${nvidia threshold}

[pixels]

${offset 10}

[color]

${outlinecolor FFAAAA}

item

• status - Display if battery is fully charged, charging, discharging or absent when running on AC
• percent - Display charge of battery in percent, if charging or discharging. Nothing is displayed if battery is fully charged or absent.
• time - Display the time remaining until the battery is fully charged or discharged at current rate. Nothing is displayed if battery is absent or if it is present but fully charged and not discharging.

${pb_battery status}

[dev] type n [factor offset]

• in or vol = voltage
• fan = fan
• temp = temperature

host username password [-i interval] [-p port] [-e "command"] [-r retries]

• host = POP3 server address
• username = POP3 user name
• password = Use an asterisk * to be prompted for password
• -i interval = Poll interval in seconds. Default is 300 (5 minutes)
• -p port = Default is 110
• -e "command" = Optional POP3 command
• -r retries = Default number of retries before giving up is 5

host username password [-i interval] [-p port] [-e "command"] [-r retries]

• host = POP3 server address
• username = POP3 user name
• password = Use an asterisk * to be prompted for password
• -i interval = Poll interval in seconds. Default is 300 (5 minutes)
• -p port = Default is 110
• -e "command" = Optional POP3 command
• -r retries = Default number of retries before giving up is 5

shell command

# get current desktop info only at startup
${pre_exec env | grep '^DESKTOP_SESSION' | cut -d'=' -f2-}

${processes}

[host] port

[mail_directory]

uri interval_in_minutes action [num_par [spaces_in_front]]

• uri = The address of the RSS feed. Can use any protocol curl supports.
• interval_in_minutes = A floating point value of minutes between checking for updates. Must be more than 0. Default is 15.
• action = One of the following:
  • feed_title
  • item_title <parameter number>
  • item_desc <parameter number>
  • item_titles <max number of items to show> = Show up to this many titles.
    • Note: Conky remembers the spaces in front of this item and uses that many spaces in front of each item shown if spaces_in_front is not specified.
• spaces_in_front = The number of spaces to put in front of item_titles.

${rss http://user:pass@example.com/news.rss 60 feed_title}
${rss http://user:pass@example.com/news.rss 60 item_title 1}
${rss http://user:pass@example.com/news.rss 60 item_title 2}

${running_processes}

${running_threads}

length [step] text

${scroll 30 ${audacious_title}}

[mail_directory]

[color]

${shadecolor 888888}

${sony_fanspeed}

[space]

${stippled_hr 5}

${sysname}

[width[, start]]

${tab 30}
${tab 5,30}

logfile lines [next_check]

${tail ~/example.txt 5 3}

port_begin port_end item <index>

• count - Total number of connections in the range. This item does not allow index to be given. The index number is required for all other items.
• rip - Remote IP address
• rhost - Remote host name
• rport - Remote port number
• rservice - Remote service name from /etc/services
• lip - Local IP address
• lhost - Local host name
• lport - Local port number
• lservice - Local service name from /etc/services

The connection index provides you with access to each connection in the port monitor. The monitor returns information for index values from 0 to n-1 connections. Values higher than n-1 are simply ignored.

Here are some examples showing how this works.

${tcp_portmon 6881 6999 count}

${tcp_portmon 22 22 rip 0}

${tcp_portmon 22 22 rip 9}

${tcp_portmon 1 1024 rhost 0}

${tcp_portmon 1 1024 rport 4}

${tcp_portmon 1 65535 lservice 14}

Note that port monitor variables which share the same port range actually refer to the same monitor, so many references to a single port range for different items and different indexes all use the same monitor internally. In other words, the program avoids creating redundant monitors.

[arg1] [arg2] [arg3] ...

template0 ${\1\2}
template1 \1: ${fs_used \2} of ${fs_size \2}
template2 \1 \2

TEXT
# After the equal sign shows what the template expands to.
${template0 node name}
# result = ${nodename}

${template1 root /}
# result = root: ${fs_used /} of ${fs_size /}

You can even pass one template to another template.
${template1 ${template2\ disk\ root} /}
# result = disk root: ${fs_used /} of ${fs_size /}

interval command

${texeci 600 ~/work.sh}

${threads}

[format]

${time %T}

size

${to_bytes ${mem}}

type num

• name - process name
• pid - process id
• cpu - current cpu usage percentage
• mem - current memory usage percentage
• mem_res - physical memory usage percentage
• mem_vsize - virtual memory size
• time - total time of activity
• uid - user id of process owner
• user - user name of process owner
• io_perc - i/o percentage
• io_read - i/o input
• io_write - i/o output

${top name 1} ${top cpu 1} ${top mem 1}
${top name 2} ${top cpu 2} ${top mem 2}

type num

${top_io name 1} ${top_io cpu 1} ${top_io io_perc 1}
${top_io name 2} ${top_io cpu 2} ${top_io io_perc 2}

type num

${top_mem name 1} ${top_mem cpu 1} ${top_mem mem 1}
${top_mem name 2} ${top_mem cpu 2} ${top_mem mem 2}

type num

${top_time name 1} ${top_time cpu 1} ${top_time time 1}
${top_time name 2} ${top_time cpu 2} ${top_time time 2}

[network_interface]

${totaldown eth0}

[network_interface]

${totalup eth0}

[mail_directory]

[timezone [format]]

${tztime America/Los_Angeles} Los Angeles
${tztime UTC %T} Universal Coordinate Time
${tztime Europe/Zurich %T} Zurich
${tztime Hongkong %T} Hong Kong

gid_number

${gid_name 1000}

uid_number

${uid_name 1000}

[mail_directory]

[mail_directory]

[mail_directory]

[mail_directory]

${updates}

[network_interface]

${upspeed eth0}

[network_interface]

${upspeedf eth0}

[network_interface] [height][,width] [gradient color 1] [gradient color 2] [scale] [-t] [-l]

${upspeedgraph eth0 20,120 888888 FFFFFF -l}

${uptime}

${uptime_short}

${user_names}

${user_number}

${user_terms}

${user_times}

console

${user_time 2}

[format]

${utime %T}

[pixels]

${voffset -16}

[cpu_number]

${voltage_mv 1}

[cpu_number]

${voltage_v 1}

URI locID data_type [interval_in_minutes]

• http://weather.noaa.gov/pub/data/observations/metar/stations/
• http://xoap.weather.com/weather/local/

The first one is free to use but the second requires you to register and obtain your partner ID and license key. These two must be written, separated by a space, into a file called .xoaprc which needs to be placed into your home directory.

'locID' must be a valid location identifier for the required uri. For the NOAA site this must be a valid ICAO (see for instance https://pilotweb.nas.faa.gov/qryhtml/icao/). For the weather.com site this must be a valid location ID (see for instance http://aspnetresources.com/tools/locid.aspx).

'data_type' must be one of the following:

• last_update - The date and time stamp of the data. The result depends on the URI used. For the NOAA site it is date yyyy/mm/dd and UTC time. For the weather.com one it is date ([m]m/[d]d/yy) and Local Time of the station.
• temperature - Air temperature. You can use the temperature_unit config setting to change units.
• cloud_cover - The highest cloud cover status
• pressure - Air pressure in millibar
• wind_speed - Wind speed in km/h
• wind_dir - Wind direction
• wind_dir_DEG - Compass wind direction
• humidity - Relative humidity in %
• weather - Any relevant weather event (rain, snow, etc.). This is not used if you are querying the weather.com site since this data is aggregated into the cloud_cover one
• icon - Weather icon only works for www.weather.com. Can be used together with the icon kit provided upon registering to their service.

'delay_in_minutes' (optional, default 30) cannot be less than 30 minutes.

This object is threaded, and once a thread is created it can't be explicitly destroyed. One thread will run for each URI specified.

Note these variables are still EXPERIMENTAL and can be subject to many future changes.

URI locID day data_type [interval_in_minutes]

For the URI, for the time being only http://xoap.weather.com/weather/local/ is supported. See weather above for details of usage

locID, see weather above.

day is a number from 0 (today) to 4 (3 days after tomorrow).

• day - Day of the week
• date - Date, in the form Mon DD (ie. Jul 14)
• low - Minimun temperature. Use the temperature_unit config setting to change units
• hi - Maximum temperature. Use the temperature_unit config setting to change units
• icon - Weather icon. Can be used together with the icon kit provided upon registering to the weather.com service
• forecast - Weather forecast (sunny, rainy, etc.)
• wind_speed - Wind speed in km/h
• wind_dir - Wind direction
• wind_dir_DEG - Compass wind direction
• humidity - Relative humidity percentage
• precipitation - Probability of having a precipitation as percentage

'delay_in_minutes' (optional, default 210) cannot be lower than 210 min.

This object is threaded, and once a thread is created it can't be explicitly destroyed. One thread will run for each URI specified. You can use any protocol that Curl supports.

Note these variables are still EXPERIMENTAL and can be subject to many future changes.

textfile

${words ~/example.txt}

Mon, Tue, Wed, Thu, Fri, Sat, Sun

Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday

Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec

January, February, March, April, May, June, July, August, September, October, November, December

• %a, %d %b %Y %T %z - RFC 2822-compliant date format (with an English locale for %a and %b)
• %a, %d %b %y %T %z - RFC 822-compliant date format (with an English locale for %a and %b)