Casey's Conky Reference with Examples

Last updated 20161206 by Casey Sprangel, IFX Group.net. This document and Conky are licensed under GNU General Public License.

This document is completely self contained and is designed to be saved locally for off-line reference if needed.

A different background color is used for each major section of this document as a subtle visual clue when you scroll or search. Every command or variable in the first column is linked so it is easier to direct attention at a specific section of this document if needed. This also makes cross reference navigation possible.

Sections (Note the background colors.)

  1. Conky Configuration File Commands - Conky settings stuff above the TEXT line.
  2. Conky Variables - Conky display stuff below the TEXT line.
  3. Time Format String Variables - Used by all TIME variables in Conky.
  4. Installing Conky - The quick Conky installation guide.
  5. Notes - Explains things or keeps things from getting too verbose.
  6. About Conky - A short explanation of Conky just in case.
  7. Conky Tips and Tricks - Examples for showing non-native and dynamic information in Conky.

Conky Command Compatibility Note

This document is written to cover the configuration file syntax supported by the widest variety of Conky versions also known as legacy format. Unfortunately somewhere in the 1.x range things got a little confusing with Ununtu repositories hosting a Conky version that did not correctly fall back to the legacy configuration file syntax. Please make sure your Conky version is before 1.0 or after 1.10.1 for best results.

Conky Configuration File Commands

The Conky configuration file(s) can be placed anywhere you want but is most commonly stored in your home directory in the .conky directory. This is a text file with two major parts divided by a line with the word TEXT. This section describes commands that appear above the TEXT command in the Conky configuration file.

VariableExplanation
alignment Aligned position on screen, may be top_left, top_right, top_middle, bottom_left, bottom_right, bottom_middle, middle_left, middle_middle, middle_right, or none. Also can be abbreviated as tl, tr, tm, bl, br, bm, ml, mm, mr. See also gap_x and gap_y.

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

append_file Append the file given as argument.

append_file /home/user/.conky/common

background Boolean value. If true Conky is forked to a background process when started.

background yes

border_inner_margin Inner border margin in pixels is the margin between the border and text.

border_inner_margin 0

border_outer_margin Outer border margin in pixels is the margin between the border and the edge of the window.

border_outer_margin 0

border_width Border width in pixels.

border_width 0

colorN Predefine a color for use inside TEXT segments. Substitute N by a digit between 0 and 9 inclusive. When specifying the color value in hex, omit the leading hash (#). See colorN text variable.

color8 995500
TEXT
${color8}

cpu_avg_samples The number of samples to average for CPU monitoring.

cpu_avg_samples 2

default_bar_size Specify a default width and height for bars. The following example is particularly useful for execbar and execibar as they do not take size arguments.

default_bar_size 0 6

default_color Default color and border color.

default_color AAAAAA

default_gauge_size Specify a default width and height for gauges in pixels. This is particularly useful for execgauge and execigauge as they do not take size arguments.

default_gauge_size 25 25

default_graph_size Specify a default width and height for graphs. This is particularly useful for execgraph and execigraph as they do not take size arguments.

default_graph_size 0 25

default_outline_color Default outline color.

default_outline_color green

default_shade_color Default shading color and border's shading color.

default_shade_color red

disable_auto_reload Set this to True or Yes to disable the inotify-based auto config reload feature.

disable_auto_reload yes

diskio_avg_samples The number of samples to average for disk I/O monitoring.

diskio_avg_samples 2

display Specify an X to connect to.

display 1

double_buffer Use the Xdbe extension? (eliminates flicker) It is highly recommended to use own window with this one so double buffer won't be so big.

double_buffer yes

draw_borders Draw borders around text? [YES or NO]

draw_borders no

draw_graph_borders Draw borders around graphs? [YES or NO]

draw_graph_borders yes

draw_outline Draw outlines around text and lines? This makes text much easier to read on a very low contrast background. [YES or NO]

draw_outline yes

draw_shades Adds a narrow shadow on text and lines to make them easier to read on relatively low contrast backgrounds. For more contrast see draw_outline. [YES or NO]

draw_shades yes

extra_newline Put an extra newline at the end when writing to stdout, useful for writing to awesome's wiboxes. [YES or NO]

extra_newline no

font Set the default font name to use in X. There are three parts.
  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 must be one of these words; bold,
If one or both of the optional parts are given a colon character must be used to separate the parts.

font Ubuntu:size=11:bold

format_human_readable If enabled, values which are in bytes are printed in human readable format (i.e., KiB, MiB, etc). If disabled, the number always shows bytes. [YES or NO]

format_human_readable yes

gap_x Gap in pixels between right or left border of screen. The following example is the same as passing -x 10 at command line. For other position related stuff, see alignment.

gap_x 10

gap_y Gap in pixels between top or bottom border of screen. The following example is the same as passing -y 10 at command line. For other position related stuff, see alignment.

gap_y 10

hddtemp_host Hostname to connect to for hddtemp objects. Defaults to 127.0.0.1. This is required for hddtemp to work.

hddtemp_host 127.0.0.1

hddtemp_port Port to use for hddtemp connections. Defaults to 7634. This is required for hddtemp to work.

hddtemp_port 7634

if_up_strictness How strict should if_up be when testing an interface for being up? The value is one of up, link or address, to check for the interface being solely up, being up and having link or being up, having link and an assigned IP address. [YES or NO]

if_up_strictness yes

imap Default global IMAP server. Arguments are: host user pass [-i interval (in seconds)] [-f 'folder'] [-p port] [-e 'command'] [-r retries]. Default port is 143, default folder is 'INBOX', default interval is 5 minutes, and default number of retries before giving up is 5. If the password is supplied as a single asterisk * you are prompted to enter the password when Conky starts.

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

imlib_cache_flush_interval Interval (in seconds) to flush Imlib2 image memory cache.

# Update image every 5 minutes
imlib_cache_flush_interval 300

imlib_cache_size Imlib2 image cache size in bytes. Defaults to 4MiB. Increase this value if you use a lot of ${image} tags. Set to 0 to disable the image cache.

imlib_cache_size 4096

Lua Scripting
lua_draw_hook_post This function, if defined, is called by Conky each iteration after drawing to the window. Requires X support. Takes any number of optional arguments. Use this hook for drawing things on top of what Conky draws. Conky puts conky_ with the trailing underscore in front of the function_name to prevent accidental calls to the wrong function unless you place conky_ in front of it yourself.

lua_draw_hook_post conky_my_overlay

lua_draw_hook_pre This function, if defined, is called by Conky each iteration before drawing to the window. Requires X support. Takes any number of optional arguments. Use this hook for drawing things under what Conky draws. Conky puts conky_ with the trailing underscore in front of the function_name to prevent accidental calls to the wrong function unless you place conky_ in front of it yourself.

lua_draw_hook_pre conky_my_background

lua_load Loads the Lua script(s) separated by spaces.

lua_load ~/.conky/scripts/example.lua ~/.conky/scripts/example2.lua

lua_shutdown_hook This function, if defined, is called by Conky at shutdown or when the configuration is reloaded. Use this hook to clean up after yourself such as freeing memory which has been allocated by external libraries via Lua. Conky puts conky_ with the trailing underscore in front of the function_name to prevent accidental calls to the wrong function unless you place conky_ in front of it yourself.

lua_shutdown_hook conky_my_cleanup

lua_startup_hook This function, if defined, is called by Conky at startup or when the configuration is reloaded. Use this hook to initialize values, or for any run-once applications. Conky puts conky_ in front of the function_name to prevent accidental calls to the wrong function unless you place conky_ with the trailing underscore in front of it yourself.

lua_startup_hook conky_my_wakeup

mail_spool Mail spool for mail checking.

mail_spool $MAIL

max_port_monitor_connections Allow each port monitor to track at most this many connections. If 0 or not set, default is 256.

max_port_monitor_connections 256

max_specials Maximum number of special things, e.g. fonts, offsets, aligns, etc. Default is 512.

max_specials 512

max_text_width When a line in the output contains width characters and the end isn't reached, the next character starts a new line. If you want to make sure that long lines don't get broken into multiple lines, set this to 0.

max_text_width 0

max_user_text Maximum size of the user text buffer in memory. At a minimum this must be large enough to hold all of the layout information below the TEXT line in your Conky config file. Default is 16384 bytes.

max_user_text 16384

maximum_width Maximum width of window in pixels.

maximum_width 200

minimum_size Minimum size of window in pixels.

maximum_size 400

mpd_host Host of Music Player Daemon MPD server. Be sure to export MPD_HOST=127.0.0.1 before using this command on a local machine.

mpd_host 127.0.0.1

mpd_password Music Player Daemon MPD server password.

mpd_password pass

mpd_port Music Player Daemon Port for the MPD server.

mpd_port 6600

music_player_interval Music player thread update interval measured in Conky update intervals. Defaults to once each time Conky updates.

music_player_interval 1

net_avg_samples The number of samples to average for network traffic data. Smaller numbers respond faster to changes in traffic. Larger numbers jump around less.

net_avg_samples 2

no_buffers Subtract file system buffers from used memory numbers. [YES or NO]

no_buffers yes

nvidia Enables the ${nvidia} variable to be used. [TRUE or FALSE]

nvidia true

out_to_console Print text to stdout standard output for viewing in terminals. [YES or NO]

out_to_console no

out_to_ncurses Print text in the console, but use ncurses so that Conky can print the text of a new update over the old text. In the future this will provide more useful things.

out_to_ncurses no

out_to_stderr Print text to stderr the standard error output. [YES or NO]

out_to_stderr no

out_to_x When set to NO there is no output in X. This is useful when you also use things like out_to_console set to YES. If you set this to NO make sure that it is placed above all other X-related settings. If you are unsure use the first line of your Conky config file to be safe. Default value is YES. [YES or NO]

out_to_x yes

override_utf8_locale Force UTF8 character parsing even when the local settings do not use UTF8? This requires XFT (X FreeType interface Library). [YES or NO]

override_utf8_locale yes

overwrite_file Overwrite the file given as argument.

overwrite_file ~/example.log

own_window Boolean, create own window to draw? This may be required in nautilus. [YES or NO]

own_window yes

own_window_class Manually set the window manager WM_CLASS name. Defaults to Conky.

own_window_class Conky

own_window_colour If own_window_transparent is set to NO, set a specified background color for Conky. Defaults to black. This command and all Conky color statements accept either a six digit hexadecimal value like ffffff (note the lack of leading #) or a valid RGB name. See /usr/lib/X11/rgb.txt for a list of supported color names.

own_window_colour 000000

own_window_hints If own_window is set to YES, you may use these window manager hints to affect the way Conky displays. Notes: Use own_window_type desktop as another way to implement many of these hints implicitly. 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 Manually set the window name. Defaults to <hostname> - Conky.

own_window_title Conky

own_window_argb_visual Boolean answer to use alpha-red-green-blue ARGB visual display? ARGB can be used for real alpha layer transparency. A composite manager is required for real transparency. This option does not work as desired, in most cases, in conjunction with own_window_type override. [YES or NO]

own_window_argb_visual no

own_window_argb_value When ARGB visuals are enabled, use this to modify the alpha value used. Valid range is 0-255, where 0 (zero) is 0% opacity, and 255 is 100% opacity.

own_window_argb_value 128

own_window_transparent Boolean, set transparency? If ARGB visual is enabled, sets background opacity to 0%. [YES or NO]

own_window_transparent yes

own_window_type If own_window is YES, you may specify type: normal, desktop, dock, panel or override. The default is normal. Desktop windows are special windows that have no window decorations; are always visible on your desktop; do not appear in your pager or taskbar; and are sticky across all workspaces. Panel windows reserve space along a desktop edge, just like panels and taskbars, preventing maximized windows from overlapping them. The edge is chosen based on the alignment option. Override windows are not under the control of the window manager. Hints are ignored. This type of window can be useful for certain situations.

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

pad_percents Pad percentages to this many decimals. Default is 0 (zero) which adds no padding.

pad_percents 2

pop3 Default global POP3 server. Arguments are: host user pass [-i interval (in seconds)] [-p port] [-e 'command'] [-r retries]. Default port is 110, default interval is 5 minutes, and default number of retries before giving up is 5. If the password is supplied as a single asterisk * character you are prompted to enter the password when Conky starts.

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

short_units Shortens units to a single character (kiB->k, GiB->G, etc.). Default is NO. [YES or NO]

short_units yes

show_graph_range Shows the time range covered by a graph. [YES or NO]

show_graph_range yes

show_graph_scale Shows the maximum value in scaled graphs. [YES or NO]

show_graph_scale yes

stippled_borders Border stippling or dashing in pixels.

stippled_borders 2

temperature_unit Desired output unit of all objects having a temperature. Parameters are either fahrenheit or celsius. Default unit is degrees Celsius.

temperature_unit celsius
#temperature_unit fahrenheit

templateN Define a template for later use inside TEXT segments. N must be a digit between 0 and 9, inclusive. The whole template must be on one line. Variables are supported in each template using a backslash \ character followed by a single digit 1 through 9 inclusive. The following special escape sequences are supported in the template and in the passed arguments.
  • \n = New line. This allows the one line template to expand to multiline output.
  • \\ = A single backslash character.
  • \ = A space character. Variables with spaces must use this method to quote them.
  • \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 Size of the standard text buffer. Default is 256 bytes. This buffer is used for intermediary text, such as individual lines, output from $exec vars, and various other variables. Increasing the size of this buffer can drastically reduce Conky's performance, but will allow for more text per variable. The size of this buffer cannot be smaller than the default value of 256 bytes.

text_buffer_size 256

times_in_seconds If true, variables that output times output a number that represents seconds. This does not affect ${time}, ${tztime} nor ${utime}. [YES or NO]

times_in_seconds yes

top_cpu_separate If set to true, CPU in top shows usage of one processor's power. If false, CPU in top shows the usage of all processors' power combined. [YES or NO]

top_cpu_separate no

top_name_width Width for ${top} name value in characters. Defaults to 15 characters.

top_name_width 20

total_run_times Total number of times for Conky to update before quitting. 0 (zero) makes Conky run forever.

total_run_times 0

update_interval Update interval in seconds. Fractions of a second are allowed using a decimal point.

update_interval 0.5

update_interval_on_battery Update interval in seconds when running on battery power.

update_interval_on_battery 5

uppercase Boolean value, if true, text is rendered in upper case. [YES or NO]

uppercase no

use_spacer Adds spaces around certain objects to stop them from moving other things around. Arguments are left, right, and none (default). The old true/false values are deprecated and default to right/none respectively. Note that this only helps if you are using a mono font, such as Bitstream Vera Sans Mono.

#use_spacer left
use_spacer right
#use_spacer none

use_xft Use Xft (X FreeType interface Library) for anti-aliased fonts and other display stuff. [YES or NO]

use_xft yes

xftalpha Alpha of Xft font. Must be a value at or between 1 and 0.

xftalpha 0.7

xftfont Xft font to use.

xftfont Ubuntu

TEXT This begins the text to be formatted on screen and must be the LAST non-display command in the Conky configuration file. After the TEXT begins the backslash (\) escapes newlines in the text section. This can be useful for cleaning up configuration files where Conky is used to pipe input to dzen2.

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

Conky Variables

These variables are used below the line with the TEXT command in the Conky configuration file. The syntax for the following commands starts with a Dollar $ sign followed by curly brackets {} with the variable and any parameters inside. The curly brackets can be omitted when the variable is a single word with no parameters or options but that can make it harder for human reading and editing later.

VariableArguments
[] = optional
Explanation
Advanced Configuration and Power Interface (ACPI)
acpiacadapter [adapter] Advanced Configuration and Power Interface (ACPI) power adapter state. On Linux the adapter option specifies the subfolder of /sys/class/power_supply containing the state information. Conky tries AC and ADP1 if there is no argument given. Non-Linux systems ignore this.

${acpiacadapter adp1}

acpifan Advanced Configuration and Power Interface (ACPI) fan state.

${acpifan}

acpitemp Advanced Configuration and Power Interface (ACPI) temperature in Celsius.

${acpitemp}

addr [interface] IP address for an interface, or No Address if no address is assigned.

${addr eth0}

addrs [interface] Shows IP address list for an interface if there is at least one address assigned. This works like addr with the addition of supporting multiple IP addresses assigned to the interface. Linux only.

${addrs eth0}

Laptops with the ADT 746x Chipset
adt746xcpu CPU temperature from therm_adt746x.

${adt746xcpu}

adt746xfan Fan speed from therm_adt746x.

${adt746xfan}

alignc [number] Align text to centre. The optional number adds spaces to the right (positive) or left (negative) side to adjust placement.
alignr [number] Right-justify text. The optional number pads the right side with N spaces.
APC (American Power Conversion) UPS (uninterruptible power supply) Daemon (apcupsd)
apcupsd host Sets up the connection to APC UPS Daemon (apcupsd). Prints nothing, defaults to localhost:3551
apcupsd_cable Shows the UPS connection type.

${apcupsd_cable}

apcupsd_charge Current battery capacity in percent.

${apcupsd_charge}

apcupsd_lastxfer Reason for last transfer from line to battery.

${apcupsd_lastxfer}

apcupsd_linev Nominal input voltage.

${apcupsd_linev}

apcupsd_load Current load in percent.

${apcupsd_load}

apcupsd_loadbar Bar showing current load.

${apcupsd_loadbar}

apcupsd_loadgauge [height][,width] Gauge that shows current load.

${apcupsd_loadgauge 10,20}

apcupsd_loadgraph [height][,width] [gradient color 1] [gradient color 2] [scale] [-t] [-l] History graph of current load.

${apcupsd_loadgraph 20,120 FFFF00 FFCC00 -l}

apcupsd_model Prints the model of the UPS.

${apcupsd_model}

apcupsd_name Prints the UPS user-defined name.

${apcupsd_name}

apcupsd_status Prints current status on-line or on-battery.

${apcupsd_status}

apcupsd_temp Current internal temperature.

${apcupsd_temp}

apcupsd_timeleft Time left to run on battery.

${apcupsd_timeleft}

apcupsd_upsmode Prints the UPS mode like standalone.

${apcupsd_upsmode}

apm_adapter Display APM AC adapter status. FreeBSD only.

${apm_adapter}

apm_battery_life Display APM battery life in percent. FreeBSD only.

${apm_battery_life}

apm_battery_time Display remaining APM battery life in hh:mm:ss or unknown if AC adapterstatus is on-line or charging. FreeBSD only.

${apm_battery_time}

Audacious Audio Player
audacious_bar [height][,width] Progress bar
audacious_bitrate Bitrate of current tune.

${audacious_bitrate}

audacious_channels Number of audio channels of current tune.

${audacious_channels}

audacious_filename Full path and filename of current tune.

${audacious_filename}

audacious_frequency Sampling frequency of current tune.

${audacious_frequency}

audacious_length Total length of current tune as MM:SS.

${audacious_length}

audacious_length_seconds Total length of current tune in seconds.

${audacious_length_seconds}

audacious_main_volume The current volume fetched from Audacious.

${audacious_main_volume}

audacious_playlist_length Number of tunes in playlist.

${audacious_playlist_length}

audacious_playlist_position Playlist position of current tune.

${audacious_playlist_position}

audacious_position Position of current tune in MM:SS format.

${audacious_position}

audacious_position_seconds Position of current tune in seconds.

${audacious_position_seconds}

audacious_status Player status. Possible choices are Playing, Paused, Stopped, Not running.

${audacious_status}

audacious_title [max length] Title of current tune with optional maximum length specifier
Laptop Battery Information
battery [battery_number] Battery status and remaining percentage capacity of ACPI or APM battery. ACPI battery number can be given as argument and points to /proc/acpi/battery/BAT0/state. Default is battery BAT0.

${battery BAT1}

battery_bar [height][,width] [battery_number] Battery percentage remaining of ACPI battery in a bar. ACPI battery number can be given as argument. Default is battery BAT0.

${battery_bar 10,20 BAT1}

battery_percent [battery_number] Battery percentage remaining for ACPI battery. ACPI battery number can be given as argument. Default is battery 0.

${battery_percent BAT1}

battery_short [battery_number] Battery status and remaining percentage capacity of ACPI or APM battery. ACPI battery number can be given as argument. Default is battery BAT0. This mode display a short status, which means that C is displayed instead of charging, D for discharging, F for full, N for not present, E for empty and U for unknown.

${battery_short BAT1}

battery_time [battery_number] Battery charge/discharge time remaining of ACPI battery. ACPI battery number can be given as argument Default is battery BAT0.

${battery_time BAT1}

blink text_and_other_conky_vars Make text_and_other_conky_vars blink on and off.

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

BMPx successor to the XMMS-based Beep Media Player
bmpx_album Album in current BMPx track.

${bmpx_album}

bmpx_artist Artist in current BMPx track.

${bmpx_artist}

bmpx_bitrate Bitrate of the current BMPx track.

${bmpx_bitrate}

bmpx_title Title of the current BMPx track.

${bmpx_title}

bmpx_track Track number of the current BMPx track.

${bmpx_track}

bmpx_uri URI of the current BMPx track.

${bmpx_uri}

buffers Amount of memory buffered.

${buffers}

cached Amount of memory cached.

${cached}

cmdline_to_pid string PID of the first process that has string in it's command line.

${cmdline_to_pid "demo"}

color [color] Change drawing color to color which is a name of a color or a hexadecimal code preceded with the #, for example #0A1B2C. If you use ncurses only the following colors are supported:
  • red
  • green
  • yellow
  • blue
  • magenta
  • cyan
  • black
  • white

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

colorN Change drawing color to predefined color N configuration option, where N is a digit between 0 and 9 inclusive; color0, color1, color2, color3, color4, color5, color6, color7, color8, color9.

color8 f9cc00
TEXT
${color8}

combine var1 var2 Places the lines of var2 to the right of the lines of var1 separated by the chars that are put between var1 and var2.

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

This gives as output cpuinfo_line1 - meminfo_line1 on line 1 and cpuinfo_line2 - on line 2. Combined variables can also be nested to place more vars next to each other.
Conky_build_arch CPU architecture Conky was built for.

${conky_build_arch}

Conky_build_date Date Conky was built.

${conky_build_date}

Conky_version Conky version number.

${conky_version}

cpu [cpu_Number] CPU usage in percents. For SMP machines, the optional CPU number can be provided as an argument. ${cpu 0} is the combined total usage, and ${cpu X} where X is a positive whole number for individual CPUs.

${cpu cpu0}% Total
${cpu 1}% Core 1
${cpu 2}% Core 2

cpubar [cpu_Number] [height][,width] Bar that shows CPU usage. Height and width are in pixels. See ${cpu} for more info on SMP hardware.

${cpubar 0 10,60}

cpugauge [cpu_Number] [height][,width] Elliptical gauge that shows CPU usage, height and width are gauge's vertical and horizontal axis respectively. See cpu for more info on SMP.

${cpugauge cpu0 20,40}

cpugraph [cpu_Number] [height][,width] [gradient color 1] [gradient color 2] [scale] [-t] [-l] CPU usage graph with optional colors in RGB hexadecimal. See ${cpu} for more info on SMP hardware. The lower case L -l switch uses a logarithmic scale to make small numbers more visible. The lower case T -t switch enables temperature gradient to make the color values change depending on the amplitude of the CPU load.

${cpugraph 0 10,120 555555 AAAAAA -l}

curl url [interval_in_minutes] Download data from URI using Curl at the specified interval. The interval may be a floating point value greater than 0, otherwise defaults to 15 minutes. Most useful when used in conjunction with Lua and the Lua API. 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.
desktop X-windows virtual desktop number or the message Not running in X if this is the case.

${desktop}

desktop_name Name of the desktop on which Conky is running or the message Not running in X if this is the case.

${desktop_name}

desktop_number Number of desktops or the message Not running in X if this is the case.

${desktop_number}

disk_protect device Disk protection status, if supported. This may need a kernel-patch. Prints either frozen or free , note the padding after the word free.

${disk_protect sda}

diskio [device] Displays current disk IO. Device is optional, and takes the form of sda for /dev/sda. Individual partitions are supported.

${diskio /dev/sda}

diskio_read [device] Displays current disk IO for reads.

${diskio_read /dev/sda}

diskio_write [device] Displays current disk IO for writes.

${diskio_write /dev/sda}

diskiograph [device] [height][,width] [gradient color 1] [gradient color 2] [scale] [-t] [-l] Disk IO activity graph. Colors defined in RGB hexadecimal. If scale is non-zero, it becomes the scale for the graph. The lower case L -l switch uses a logarithmic scale to make small numbers more visible. The lower case T -t switch enables temperature gradient to make the color values change depending on the amplitude of the activity.

${diskiograph /dev/sda 10,120 555555 AAAAAA -l}

diskiograph_read [device] [height][,width] [gradient color 1] [gradient color 2] [scale] [-t] [-l] Disk IO graph for reads. Colors are defined in RGB hexadecimal. If scale is non-zero, it becomes the scale for the graph. The lower case L -l switch uses a logarithmic scale to make small numbers more visible. The lower case T -t switch enables temperature gradient to make the color values change depending on the amplitude of the activity.

${diskiograph_read /dev/sda 10,120 555555 AAAAAA -l}

diskiograph_write [device] [height][,width] [gradient color 1] [gradient color 2] [scale] [-t] [-l] Disk IO graph for writes. Colors are defined in RGB hexadecimal. If scale is non-zero, it becomes the scale for the graph. The lower case L -l switch uses a logarithmic scale to make small numbers more visible. The lower case T -t switch enables temperature gradient to make the color values change depending on the amplitude of the activity.

${diskiograph_write /dev/sda 10,120 555555 AAAAAA -l}

downspeed [network_interface] Download speed in suitable IEC (International Electrotechnical Commission) units.

${downspeed eth0}

downspeedf [network_interface] Download speed in KiB with one decimal place.

${downspeedf eth0}

downspeedgraph [network_interface] [height][,width] [gradient color 1] [gradient color 2] [scale] [-t] [-l] Download speed graph. Colors are defined in RGB hexadecimal. If scale is non-zero, it becomes the scale for the graph. Uses a logarithmic scale (to see small numbers) when you use -l switch. Takes the switch -t to use a temperature gradient, which makes the gradient values change depending on the amplitude of a particular graph value.

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

draft_mails [mail_directory] Number of mails marked as draft in the specified mailbox or mail spool if not. Only maildir type mailboxes are supported, mbox type will return -1.
else Text to show only when the previous ${if_*} is not true. Everything between the ${else} and the ${endif} is shown.

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

endif Ends an ${if_*} block.

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

entropy_avail Current entropy available for crypto freaks.

${entropy_avail}

entropy_bar [height][,width] Normalized bar of available entropy for crypto freaks.

${entropy_bar 10,20}

entropy_perc Percentage of entropy available in comparison to the poolsize.

${entropy_perc}

entropy_poolsize Total size of system entropy pool for crypto freaks.

${entropy_poolsize}

eval string Evaluates given string according to the rules of TEXT interpretation, i.e. parsing any contained text object specifications into their output, any occuring '$$' into a single '$' and so on. The output is then being parsed again.

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

eve api_userid api_key character_id Fetches your currently training skill from the Eve Online API servers (http://www.eve-online.com/) and displays the skill along with the remaining training time.
exec command Executes a shell command and displays the output in Conky. Warning: this takes a lot more resources than other variables. I'd recommend coding wanted behaviour in C and posting a patch.

${exec cat /etc/debian_version}

execbar command Same as ${exec} except if the first value returned is a number between 0-100, it will use that number for a bar. The size for bars can be controlled via the default_bar_size config setting.
execgauge command Same as ${exec} except if the first value returned is a number between 0-100, it will use that number for a gauge. The size for gauges can be controlled via the default_gauge_size config setting.
execgraph [-t] [-l] command Same as ${execbar} but graphs values. Uses a logarithmic scale when the log option, lower case L -l switch is given. This makes small numbers more visible. Values still have to be between 0 and 100. The size for graphs can be controlled via the default_graph_size config setting. Takes the switch -t to use a temperature gradient, which makes the gradient values change depending on the amplitude of a particular graph value. Try it and see. If -t or -l is your first argument, you may need to precede it by a space ( ).
execi interval command Same as ${exec} but with a specific interval. Interval can't be less than update_interval in configuration. See also ${texeci}.

${execi 300 cat /etc/debian_version}

execibar interval command Same as execbar except with an interval.
execigauge interval command Same as execgauge but takes an interval arg and gauges values.
execigraph interval [-t] [-l] command Same as execgraph but takes an interval arg and graphs values. If -t or -l is your first argument, you may need to precede it by a space ( ).
execp command Executes a shell command and displays the output in Conky. Warning: this takes a lot more resources than other variables. I'd recommend coding wanted behaviour in C and posting a patch. This differs from ${exec} in that it parses the output of the command, so you can insert things like ${color red}hi!${color} in your script and have it correctly parsed by Conky. Caveats: Conky parses and evaluates the output of ${execp} every time Conky loops, and then destroys all the objects. If you try to use anything like ${execi} within the ${execp} statement it will functionally run at the same interval that the ${execp} statement runs, as it is created and destroyed at every interval.
execpi interval command Same as execp but with specific interval. Interval can't be less than update_interval in configuration. Note the output from the execpi command is still parsed and evaluated at every update interval.
flagged_mails [mail_directory] Number of mails marked as flagged in the specified mailbox or mail spool if not. Only maildir type mailboxes are supported, mbox type will return -1.
font [font][:weight][:size] Specify a font with optional weight and size. This font applies to the current line and everything following. You can use ${font} with no arguments to change back to the default font much like with ${color}

${font Ubuntu:bold:size=12}

format_time seconds format Format time given in seconds. This variable only works when the times_in_seconds configuration setting is ON.
Format is a string that should start and end with a double quote (") character. The double quote characters are not part of the output. The \w,\d,\h,\m,\s,\(,\) and \\ pairs are replaced by weeks, days, hours, minutes, seconds, (, ) and \ respectively. If a unit is not given, its value is expressed in the highest unit lower then the one left out. Text between paren characters is not visible if a replaced unit in the text is 0. If seconds is a decimal number you can see the numbers behind the point by using \S followed by a number that specifies the amount of digits behind the point that you want to see. Maximum is 9. You can also place a x behind \Sx so you have all digits behind the point and no trailing zeros up to a maximum of 9.
forwarded_mails [mail_directory] Number of mails marked as forwarded in the specified mailbox or mail spool if not. Only maildir type mailboxes are supported, mbox type will return -1.
freq [cpu_number] Returns CPU #n's frequency in MHz. CPUs are counted from 1. If omitted, the parameter defaults to 1.

${freq}MHz

freq_g [cpu_number] Returns CPU #n's frequency in GHz. CPUs are counted from 1. If omitted, the parameter defaults to 1.

${freq_g}Ghz

File System Information
fs_bar [height][,width] file_system Bar that shows how much space is used on a file system. Height and Width are the height and width in pixels. File_system is any file or folder on that file system.

${fs_bar /home}

fs_bar_free [height][,width] fs Bar that shows how much space is free on a file system. height is the height in pixels. fs is any file on that file system.

${fs_bar_free /home}

fs_free [file_system] Free space on a file system available for users.

${fs_free /home}

fs_free_perc [file_system] Free percentage of space on a file system available for users.

${fs_free_perc /home}

fs_size [file_system] File system size.

${fs_size /home}

fs_type [file_system] File system type.

${fs_type /home}

fs_used [file_system] File system used space.

${fs_used /home}

fs_used_perc [file_system] Percent of file system used space.

${fs_used_perc /home}

goto number The next element is printed at position number from the left hand side of the Conky window. This is measured in characters and is useful for creating uniform indents and the illusion of columns.

${goto 10}

gw_iface Displays the default route's interface or multiple or none accordingly.

${gw_iface}

gw_ip Displays the default gateway's IP or multiple or none accordingly.

${gw_ip}

hddtemp [device] Displays temperature of a selected hard disk drive as reported by the hddtemp daemon. Use hddtemp_host and hddtemp_port to specify a host and port for all hddtemp objects. If the device parameter is not given, the first disk returned by the hddtemp daemon is used.

${hddtemp}

head logfile lines [next_check] Displays first N lines of supplied text file. The file is checked every next_check update. If next_check is not supplied, Conky defaults to 2. Max of 30 lines can be displayed, or until the text_buffer_size is filled.
hr [height] Horizontal line, height is the height in pixels.

${hr 1}

hwmon [device] type n [factor offset] Hwmon sensor from sysfs (Linux 2.6 or higher). Parameter device is the device name and may be omitted if you have only one hwmon device. Parameter type is one of the following.
  • in = Voltage (same as vol)
  • vol = Voltage (same as in)
  • fan = Fan speed
  • temp = System temperature
Parameter n is the number of the sensor. See /sys/class/hwmon/ on your local computer. The optional arguments factor and offset allow pre-calculation of the raw input, which is calculated as: input = input * factor + offset. Note they have to be given as decimal values with at least one decimal place.

${hwmon temp 1}°C

i2c [device] type n [factor offset] I2C sensor from sysfs (Linux 2.6). Parameter dev may be omitted if you have only one I2C device. Parameter type is either 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp' meaning temperature. Parameter n is number of the sensor. See /sys/bus/i2c/devices/ on your local computer. The optional arguments 'factor' and 'offset' allow precalculation of the raw input, which is being modified as follows: 'input = input * factor + offset'. Note that they have to be given as decimal values with at least one decimal place.
Dell Inspiron Laptops
i8k_ac_status If running the i8k kernel driver for Dell Inspiron laptops this shows whether ac power is on, as listed in /proc/i8k translated to human-readable format. This is by default not enabled by i8k itself.

${i8k_ac_status}

i8k_bios If running the i8k kernel driver for Inspiron laptops, displays the bios version as listed in /proc/i8k.

${i8k_bios}

i8k_buttons_status If running the i8k kernel driver for Inspiron laptops, displays the volume buttons status as listed in /proc/i8k.

${i8k_buttons_status}

i8k_cpu_temp If running the i8k kernel driver for Inspiron laptops, displays the cpu temperature in Celsius, as reported by /proc/i8k.

${i8k_cpu_temp}

i8k_left_fan_rpm If running the i8k kernel driver for Inspiron laptops, displays the left fan's rate of rotation, in revolutions per minute as listed in /proc/i8k. In some laptops i8k reports these fans in reverse order.

${i8k_left_fan_rpm}

i8k_left_fan_status If running the i8k kernel driver for Inspiron laptops, displays the left fan status as listed in /proc/i8k translated to human-readable format. Beware, some laptops i8k reports these fans in reverse order.

${i8k_left_fan_status}

i8k_right_fan_rpm If running the i8k kernel driver for Inspiron laptops, displays the right fan's rate of rotation, in revolutions per minute as listed in /proc/i8k. Beware, some laptops i8k reports these fans in reverse order.

${i8k_right_fan_rpm}

i8k_right_fan_status If running the i8k kernel driver for Inspiron laptops, displays the right fan status as listed in /proc/i8k translated to human-readable format. Beware, some laptops i8k reports these fans in reverse order.

${i8k_right_fan_status}

i8k_serial If running the i8k kernel driver for Inspiron laptops, displays your laptop serial number as listed in /proc/i8k.

${i8k_serial}

i8k_version If running the i8k kernel driver for Inspiron laptops, displays the version formatting of /proc/i8k.

${i8k_version}

IBM Laptops
ibm_brightness If running the IBM ACPI, displays the brightness of the laptops's LCD. Range is 0 to 7.

${ibm_brightness}

ibm_fan If running the IBM ACPI, displays the fan speed.

${ibm_fan}

ibm_temps number If running the IBM ACPI, displays the temperatures from the IBM temperature sensors. Number has the range of 0 to 7 inclusive. Sensor 0 is on the CPU, 3 is on the GPU.

${ibm_temps 0}

ibm_volume If running the IBM ACPI, displays the master volume, controlled by the volume keys (0-14).

${ibm_volume}

iconv_start codeset_from codeset_to Convert text from one codeset to another using GNU iconv. Needs to be stopped with iconv_stop. All characters between the start and stop are converted.

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

iconv_stop Stop iconv codeset conversion.

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

Conditionals
if_empty [var] If Conky variable VAR is empty, display everything between ${if_empty} and the matching ${endif}.

${if_empty var}
${else}
${endif}

if_existing file_name [string] If the named file exists show everything between ${if_existing} and the matching ${endif}. The optional second parameter checks for file containing the specified string and prints everything between ${if_existing} and the matching ${endif}.

${if_existing ~/results.log "fail"}
${endif}

if_gw If there is at least one default gateway, display everything between ${if_gw} and the matching ${endif}.

${if_gw}
${else}
${endif}

if_match expression Evaluates the given boolean expression, printing everything between ${if_match} and the matching ${endif} depending on whether the evaluation returns true or not. Valid expressions consist of a left side, an operator and a right side. Left and right sides are being parsed for contained text objects before evaluation. Recognized left and right side types are:
  • double - Argument consists of only digits and a single dot.
  • long - Argument consists of only digits.
  • string - Argument is enclosed in double quotation marks (").
Valid operands are: >, <, >=, <=, ==, !=.

${if_match "${tcp_portmon 1 65534 rip eth0}">""}
${endif}

if_mixer_mute [mixer] If mixer exists, display everything between ${if_mixer_mute} and the matching ${endif}. If no mixer is specified, Vol is used.

${if_mixer_mute}
${endif}

if_mounted [mountpoint] If MOUNTPOINT is mounted, display everything between ${if_mounted} and the matching ${endif}.

${if_mounted /media/thumbdrive}
${endif}

if_mpd_playing If mpd is playing or paused, display everything between ${if_mpd_playing} and the matching ${endif}.

${if_mpd_playing}
${else}
${endif}

if_running [process] If PROCESS is running, display everything ${if_running} and the matching ${endif}. This uses the pidof command, so the -x switch is also supported.
if_smapi_bat_installed [battery_number] When using SMAPI, if the battery with index battery_number (integer number only) is installed, display everything between ${if_smapi_bat_installed} and the matching ${endif}. Default battery_number is 0.

${if_smapi_bat_installed 1}
${endif}

if_up [interface] If INTERFACE exists and is up, display everything between ${if_up} and the matching ${endif}.

${if_up eth0}
${else}
${endif}

if_updatenr [update_number] If it's the UPDATENR-th time that Conky updates, display everything between ${if_updatenr} and the matching ${endif}. The counter resets when the highest UPDATENR is reached. The following example sets the highest UPDATENR to 4.

${if_updatenr 1}foo${endif}
${if_updatenr 2}bar${endif}
${if_updatenr 4}${endif}

This shows foo 25% of the time followed by bar 25% of the time followed by nothing the other half of the time.
if_xmms2_connected Display everything between ${if_xmms2_connected} and the matching ${endif} if xmms2 is running.

${if_xmms2_connected}
${else}
${endif}

image <path to image> [-p x,y] [-s WxH] [-n] [-f interval] Renders an image from the path specified using Imlib2. Takes 4 optional arguments: a position (-p x,y), a size (-s width x height), a no-cache (-n) switch, and a cache flush (-f #) interval in seconds. Also see imlib_cache_flush_interval. Changing the x,y position moves the position of the image within the Conky window, and changing the WxH scales the image from the x,y center point. If you specify the no-cache flag (-n), the image will not be cached in memory forcing it to be loaded at each Conky refresh. Alternately, you can specify the -f # switch to specify a cache flush interval for a particular image in seconds.

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

This renders cheeseburger.jpg centered at (20,20) scaled to 200x200 pixels updated once every 5 minutes. Conky does not make any attempt to adjust the position or any other formatting of images, they are just rendered as per the arguments passed. The only reason ${image} is part of the TEXT section is to allow for runtime modifications to the image file directly through execp, lua_parse, or through some other method. Images that do not change should be part of the background or wallpaper for best performance.
imap_messages [args] Displays the number of messages in your global IMAP inbox by default. You can define individual IMAP inboxes separately by passing arguments to this object. Arguments are: host user pass [-i interval (in seconds)] [-f "folder"] [-p port] [-e "command"] [-r retries]. Default port is 143, default folder is INBOX, default interval is 5 minutes, and default number of retries before giving up is 5. If the password is supplied as *, you are prompted to enter the password when Conky starts.
imap_unseen [args] Displays the number of unseen messages in your global IMAP inbox by default. You can define individual IMAP inboxes separately by passing arguments to this object. Arguments are: host user pass [-i interval (in seconds)] [-f "folder"] [-p port] [-e "command"] [-r retries]. Default port is 143, default folder is INBOX, default interval is 5 minutes, and default number of retries before giving up is 5. If the password is supplied as *, you are prompted to enter the password when Conky starts.
include filename Loads the specified config file, internally applies the config settings as if they appeared above the TEXT line in the original file and places the vars where the include variable appeared. This does not modify the source file.

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

ioscheduler disk Prints the current ioscheduler used for the given disk name. The disk name looks like hda or sdb.

${ioscheduler sda}

kernel Shows current running Kernel version.

${kernel}

laptop_mode The value of /proc/sys/vm/laptop_mode

${laptop_mode}

lines textfile Displays the number of lines in the given file.

${lines ~/example.txt}

loadavg [1|2|3] System load average, 1 is for past 1 minute, 2 for past 5 minutes and 3 for past 15 minutes. Without argument, prints all three values separated by whitespace.

${loadavg 1}

loadgraph [height][,width] [gradient color 1] [gradient color 2] [scale] [-t] [-l] Load1 average graph, similar to xload, with optional colors in RGB hexadecimal. Uses a logarithmic scale (to see small numbers) when you use the -l switch. Takes the switch -t to use a temperature gradient, which makes the gradient values change depending on the amplitude of a particular graph value (try it and see).

${loadgraph 20,120 888888 FFFFFF -l}

Lua Scripting
lua function_name [function parameters] Executes a Lua function with given parameters, then prints the returned string. See also lua_load on how to load scripts. Conky puts conky_ in front of function_name to prevent accidental calls to the wrong function unless you put you place conky_ in front of it yourself.
lua_bar [height, width] function_name [function parameters] Executes a Lua function with given parameters and draws a bar. Expects result value to be an integer between 0 and 100. See also lua_load on how to load scripts. Conky puts conky_ in front of the function_name to prevent accidental calls to the wrong function unless you put you place conky_ in front of it yourself.
lua_gauge [height, width] function_name [function parameters] Executes a Lua function with given parameters and draws a gauge. Expects result value to be an integer between 0 and 100. See also lua_load on how to load scripts. Conky puts conky_ in front of the function_name to prevent accidental calls to the wrong function unless you put you place conky_ in front of it yourself.
lua_graph function_name [height][,width] [gradient color 1] [gradient color 2] [scale] [-t] [-l] Executes a Lua function with and draws a graph. Expects result value to be any number, and by default will scale to show the full range. See also lua_load on how to load scripts. Takes the switch '-t' to use a temperature gradient, which makes the gradient values change depending on the amplitude of a particular graph value (try it and see). Conky puts conky_ in front of the function_name to prevent accidental calls to the wrong function unless you put you place conky_ in front of it yourself.
lua_parse function_name [function parameters] Executes a Lua function with given parameters as per $lua, then parses and prints the result value as per the syntax for Conky's TEXT section. See also lua_load on how to load scripts. Conky puts conky_ in front of the function_name to prevent accidental calls to the wrong function unless you put you place conky_ in front of it yourself.
machine Shows the machine CPU class information. For example, x86_64 or i686.

${machine}

mails [mailbox] Mail count in the specified mailbox or your mail spool if not. Both mbox and maildir type mailboxes are supported. You can use a program like fetchmail to get mails from some server using your favourite protocol. See also new_mails.
mboxscan [-n] [-fw] [-sw] mbox Print a summary of recent messages in an mbox format mailbox file. N is number of message to print, FW is from width, SW is subject width. The mbox parameter is the filename of the mailbox enclosed in double quotes (").

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

mem Amount of memory in use.

${mem}

membar [height][,width] Bar that shows amount of memory in use.

${membar 10,60}

memeasyfree Amount of free memory including the memory that is very easily freed like buffers/cache.

${memeasyfree}

memfree Amount of free memory.

${memfree}

memgauge [height][,width] Gauge that shows amount of memory in use. See ${cpugauge} for additional formatting information.
memgraph [height][,width] [gradient color 1] [gradient color 2] [scale] [-t] [-l] Memory usage graph. Uses a logarithmic scale to make small numbers more visible when you use the -l switch. Takes the switch '-t' to use a temperature gradient, which makes the gradient values change depending on the amplitude of a particular graph value.

${memgraph 10,120 555555 AAAAAA -l}

memmax Total amount of memory available to the host operating system. In systems with video display hardware that uses system RAM instead of discrete video memory, this number is always lower than the physical amount of RAM installed.

${memmax}

memperc Percentage of memory in use.

${memperc}

Audio Mixer
mixer [device] Prints the mixer value as reported by the OS. On Linux, this variable uses the OSS emulation which requires the proper kernel module loaded. Default mixer is Vol, but you can specify one of the available OSS controls:
  • Bass
  • CD
  • Digital1
  • Digital2
  • Digital3
  • IGain
  • Line
  • Line1
  • Line2
  • Line3
  • Mic
  • Mix
  • Monitor
  • OGain
  • Pcm
  • Pcm2
  • PhoneIn
  • PhoneOut
  • Radio
  • Rec
  • Spkr
  • Synth
  • Trebl
  • Video
  • Vol

${mixer vol}

mixerbar <device> [size_x[,size_y]] Displays mixer value in a bar as reported by the OS. See mixer for details on arguments.

${mixerbar vol 10,20}

mixerl [device] Prints the left channel mixer value as reported by the OS. See mixer for details on arguments.

${mixerl vol}

mixerlbar <device> [size_x[,size_y]] Displays the left channel mixer value in a bar as reported by the OS. See mixer for details on arguments.

${mixerlbar vol 10,20}

mixerr [device] Prints the right channel mixer value as reported by the OS. See mixer for details on arguments.

${mixerr vol}

mixerrbar <device> [size_x[,size_y]] Displays the right channel mixer value in a bar as reported by the OS. See mixer for details on arguments.

${mixerrbar vol 10,20}

Music on Console Player
moc_album Album of the current MOC song.

${moc_album}

moc_artist Artist of the current MOC song.

${moc_artist}

moc_bitrate Bitrate in the current MOC song.

${moc_bitrate}

moc_curtime Current time of the current MOC song.

${moc_curtime}

moc_file File name of the current MOC song.

${moc_file}

moc_rate Rate of the current MOC song.

${moc_rate}

moc_song The current song name being played in MOC.

${moc_song}

moc_state Current state of MOC; playing, stopped etc.

${moc_state}

moc_timeleft Time left in the current MOC song.

${moc_timeleft}

moc_title Title of the current MOC song.

${moc_title}

moc_totaltime Total length of the current MOC song.

${moc_totaltime}

monitor Number of the monitor on which Conky is running or the message Not running in X if this is the case.

${monitor}

monitor_number Number of monitors or the message Not running in X if this is the case.

${monitor_number}

Music Player Daemon (MPD)
mpd_album Album in current MPD song.

${mpd_album}

mpd_artist Artist in current MPD song must be enabled at compile.

${mpd_artist}

mpd_bar [height][,width] Bar of mpd's progress
mpd_bitrate Bitrate of current song.

${mpd_bitrate}

mpd_date Date of current song.

${mpd_date}

mpd_elapsed Song's elapsed time.

${mpd_elapsed}

mpd_file Prints the file name of the current MPD song.

${mpd_file}

mpd_length Song's length.

${mpd_length}

mpd_name Prints the MPD name field.

${mpd_name}

mpd_percent Percent of song's progress.

${mpd_percent}

mpd_random Shows the current random status On or Off.

${mpd_random}

mpd_repeat Repeat status On or Off.

${mpd_repeat}

mpd_smart [max_length] Shows the song name in either the form artist - title or file name, depending on what is available.
mpd_status Playing, stopped, et cetera.

${mpd_status}

mpd_title [max_length] Title of current MPD song
mpd_track Prints the MPD track field.

${mpd_track}

mpd_vol MPD's volume.

${mpd_vol}

nameserver [index] Print a DNS nameserver from /etc/resolv.conf. Index starts at and defaults to 0.

${nameserver 0}

new_mails [mailbox] Unread mail count in the specified mailbox or mail spool if not. Both mbox and maildir type mailboxes are supported.
nodename Hostname of the local system.

${nodename}

nodename_short Short hostname. Same as hostname -s shell command.

${nodename_short}

nvidia item Nvidia graphics card support using the XNVCtrl library. Each item option can be shortened to the least significant part as highlighted below. Temperatures are shown as float, all other values as integer.
  • 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}

offset [pixels] Move text over by the given number of pixels to the right. Negative values move to the left. See also ${voffset}.

${offset 10}

outlinecolor [color] Change outline color. Same rules as default_outline_color.

${outlinecolor FFAAAA}

pb_battery item If running on Apple Powerbook/iBook display information on battery status. The item parameter specifies, what information to display. Exactly one item must be specified. Valid items are:
  • 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}

Information by Program Identifier
pid_chroot pid Directory used as root directory by the process. This will always be / unless the process did a chroot syscall.

${pid_chroot 2649}

pid_cmdline pid Command line this process was invoked with.

${pid_cmdline 2649}

pid_cwd pid Current working directory of the process.

${pid_cwd 2649}

pid_environ pid varname Contents of a environment-var of the process
pid_environ_list pid List of environment-vars that the process can see.

${pid_environ_list 2649}

pid_exe pid Path to executed command that started the process.

${pid_exe 1679}

pid_nice pid The nice value of the process.

${pid_nice 2649}

pid_openfiles pid List of files that the process has open.

${pid_openfiles 2649}

pid_parent pid The pid of the parent of the process.

${pid_parent 2649}

pid_priority pid The priority of the process. See priority in man 5 proc.

${pid_priority 2649}

pid_read pid Total number of bytes read by the process.

${pid_read 2649}

pid_state pid State of the process. Running, Sleeping, Waiting, Zombie, Traced, Stopped, Paging.

${pid_state 2649}

pid_state_short pid One of the chars in RSDZTW representing the state of the process where
  • R = running
  • S = sleeping in an interruptible wait
  • D = waiting in uninterruptible disk sleep
  • Z = zombie
  • T = traced or stopped (on a signal)
  • W = paging

${pid_state_short 2649}

pid_stderr pid Filedescriptor binded to the STDERR of the process.

${pid_stderr 2649}

pid_stdin pid Filedescriptor binded to the STDIN of the process.

${pid_stdin 2649}

pid_stdout pid Filedescriptor binded to the STDOUT of the process.

${pid_stdout 2649}

pid_threads pid Number of threads in process containing this thread.

${pid_threads 2649}

pid_thread_list pid List with pid's from threads from this process.

${pid_thread_list 2649}

pid_time_kernelmode pid Amount of time that the process has been scheduled in kernel mode in seconds.

${pid_time_kernelmode 2649}

pid_time_usermode pid Amount of time that the process has been scheduled in user mode in seconds.

${pid_time_usermode 2649}

pid_time pid Sum of $pid_time_kernelmode and $pid_time_usermode.

${pid_time 2649}

pid_uid pid The real uid of the process.

${pid_uid 2649}

pid_euid pid The effective uid of the process.

${pid_euid 2649}

pid_suid pid The saved set uid of the process.

${pid_suid 2649}

pid_fsuid pid The file system uid of the process.

${pid_fsuid 2649}

pid_gid pid The real gid of the process.

${pid_gid 2649}

pid_egid pid The effective gid of the process.

${pid_egid 2649}

pid_sgid pid The saved set gid of the process.

${pid_sgid 2649}

pid_fsgid pid The file system gid of the process.

${pid_fsgid 2649}

pid_vmpeak pid Peak virtual memory size of the process.

${pid_vmpeak 2649}

pid_vmsize pid Virtual memory size of the process.

${pid_vmsize 2649}

pid_vmlck pid Locked memory size of the process.

${pid_vmlck 2649}

pid_vmhwm pid Peak resident set size or high water mark of the process.

${pid_vmhwm 2649}

pid_vmrss pid Resident set size of the process.

${pid_vmrss 2649}

pid_vmdata pid Data segment size of the process.

${pid_vmdata 2649}

pid_vmstk pid Stack segment size of the process.

${pid_vmstk 2649}

pid_vmexe pid Text segment size of the process.

${pid_vmexe 2649}

pid_vmlib pid Shared library code size of the process.

${pid_vmlib 2649}

pid_vmpte pid Page table entries size of the process.

${pid_vmpte 2649}

pid_write pid Total number of bytes written by the process.

${pid_write 2649}

platform [dev] type n [factor offset] Platform sensor from sysfs (Linux 2.6). Parameter dev may be omitted if you have only one platform device. Platform type options:
  • in or vol = voltage
  • fan = fan
  • temp = temperature
Parameter n is number of the sensor. See /sys/bus/platform/devices/ on your local computer. The optional arguments factor and offset allow precalculation of the raw input, which is being modified as follows: input = input * factor + offset. Note that they have to be given as decimal values (i.e. contain at least one decimal place).
pop3_unseen [args] Displays the number of unseen messages in your global POP3 inbox by default. You can define individual POP3 inboxes separately by passing arguments to this object. Arguments are: host user pass [-i interval (in seconds)] [-p port] [-e 'command'] [-r retries]. Default port is 110, default interval is 5 minutes, and default number of retries before giving up is 5. If the password is supplied as an asterisk *, you are prompted to enter the password when Conky starts.
pop3_used host user pass [-i interval (in seconds)] [-p port] [-e "command"] [-r retries] If no arguments are given this shows the amount of space (in MiB, 2^20) used in your global POP3 inbox. You can define individual POP3 inboxes separately by providing the server and account information. Default port is 110, default interval is 5 minutes, and default number of retries before giving up is 5. If the password is supplied as an asterisk *, you are prompted to enter the password when Conky starts.
pre_exec shell command Executes a shell command only one time before Conky displays anything and shows output as text.

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

Note: This command may not work as documented in Conky versions after 1.0. Use ${execi} with a very long interval to simulate this function.
processes Total processes including both sleeping and running states.

${processes}

read_tcp [host] port Connects to a tcp port on a host. The default host localhost reads every char available at the moment and shows them.
replied_mails [mail_directory] Number of mails marked as replied in the specified mailbox or mail spool if not. Only maildir type mailboxes are supported, mbox type will return -1.
rss uri interval_in_minutes action [num_par [spaces_in_front]] Download and parse RSS feeds. The interval may be a floating point value greater than 0, otherwise defaults to 15 minutes.
Action may be one of the following:
  • feed_title
  • item_title <parameter number>
  • item_desc <parameter number>
  • item_titles <max number of items to show> - Conky remembers the spaces_in_front of this item and uses that many spaces in front of each item shown.
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.

${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 processes (not sleeping), requires Linux kernel 2.6 or higher.

${running_processes}

running_threads Number of running (runnable) threads. Linux only.

${running_threads}

scroll length [step] text Scroll text by step characters showing length number of characters at the same time. The text may also contain Conky variables. Step is optional and defaults to 1 if not set. If a variable creates output on multiple lines then the lines are placed behind each other separated with a | sign. If you change the textcolor inside ${scroll} it automatically returns to the old value at the end. The end and the start of text is separated by length number of spaces.
seen_mails [mail_directory] Number of mails marked as seen in the specified mailbox or mail spool if not. Only maildir type mailboxes are supported, mbox type will return -1.
shadecolor [color] Change the shading color. Uses same rules as default_shade_color.

${shadecolor 888888}

Simple Message Application Programming Interface
smapi [args] When using smapi, display contents of the /sys/devices/platform/smapi directory. ARGS are either (FILENAME) or bat [index] (FILENAME) to display the corresponding file content. This is a very raw method of accessing the smapi values. When available, better use one of the smapi_* variables instead.
smapi_bat_bar [index][,height][,width] When using smapi, display the remaining capacity of the battery with index INDEX as a bar.
smapi_bat_perc [index] When using smapi, display the remaining capacity in percent of the battery with index INDEX. This is a separate variable because it supports the 'use_spacer' configuration option.
smapi_bat_power index When using smapi, display the current power of the battery with index INDEX in watt. This is a separate variable because the original read out value is being converted from mW. The sign of the output reflects charging (positive) or discharging (negative) state.
smapi_bat_temp index When using smapi, display the current temperature of the battery with index INDEX in degree Celsius. This is a separate variable because the original read out value is being converted from milli degree Celsius.
sony_fanspeed Displays the Sony VAIO fanspeed information if sony-laptop kernel support is enabled. Linux only.

${sony_fanspeed}

stippled_hr [space] Stippled or dashed horizontal line. The space number is the number of pixels for the gaps.

${stippled_hr 5}

swap Amount of swap in use.

${swap}

swapbar [height][,width] Bar that shows amount of swap in use.

${swapbar 10,60}

swapfree Amount of free swap.

${swapfree}

swapmax Total amount of swap.

${swapmax}

swapperc Percentage of swap in use.

${swapperc}

sysname System name, Linux for example.

${sysname}

tab [width[, start]] Puts a tab of the specified width, optionally starting from column start. The unit is pixels for both arguments.
tail logfile lines [next_check] Displays last lines number of lines of supplied text file. The file is checked every next_check times Conky updates. If next_check is not supplied, Conky defaults to 2. Max of 30 lines can be displayed or until the text_buffer_size is filled.

${tail ~/example.txt 5 300}

tcp_portmon port_begin port_end item <index> TCP port for both IPv6 and IPv4 to monitor for specified local port activity. Port numbers must be in the range 1 to 65535.

The following item names can be used for monitoring.
  • 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}

Displays the number of connections in the bittorrent port range.

${tcp_portmon 22 22 rip 0}

Displays the remote host IP of the first sshd connection.

${tcp_portmon 22 22 rip 9}

Displays the remote host IP of the tenth sshd connection.

${tcp_portmon 1 1024 rhost 0}

Displays the remote host name of the first connection on a privileged port.

${tcp_portmon 1 1024 rport 4}

Displays the remote host port of the fifth connection on a privileged port.

${tcp_portmon 1 65535 lservice 14}

Displays the local service name of the fifteenth connection in the range of all ports.

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.

templateN [arg1] [arg2] [arg3] ... Evaluate the content of the templateN configuration variable where N is a value between 0 and 9 inclusive, applying substitutions as described in the documentation of the corresponding configuration variable.

The arguments are optional, but if any are given all must be given to match the highest referred index in the template. You can use the same special sequences in each argument as the ones valid for a template definition, e.g. to allow an argument to contain a whitespace the each space must be escaped. Also simple nesting of templates is possible this way. Here are some examples showing template definitions and use. Note the part below the TEXT line shows how each template is expanded.

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}
# = ${nodename}
${template1 root /}
# = root: ${fs_used /} of ${fs_size /}
You can even pass one template to another template.
${template1 ${template2\ disk\ root} /}
# = disk root: ${fs_used /} of ${fs_size /}

texeci interval command Runs a command at an interval inside a thread and displays the output. Same as ${execi} except the command is run inside a thread. Use this if you have a slow script to keep Conky updating. You should make the interval slightly longer then the time it takes your script to execute. For example, if you have a script that takes 5 seconds to execute, you should make the interval at least 6 seconds. See also ${execi}. This object will clean up the thread when it is destroyed, so it can safely be used in a nested fashion, though it may not produce the desired behaviour if used this way.
threads Total threads.

${threads}

time [format] Local time information customized with a format string. See Time Format String Variables below for more information about the format codes.

${time %T}

to_bytes size If size is a number followed by a size-unit (kilobyte,mb,GiB,...) then it converts the size to bytes and shows it without unit, otherwise it just shows 'size'.
top type num This shows information from the top command where processes are ranked from highest to lowest in terms of cpu usage. The types are:
  • 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
The num parameter identifies the process as listed by the top command where 1 is the highest. A maximum of 10 processes (numbered 1 through 10) are supported.

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

top_io type num Same as ${top} except sorted by the amount of I/O the process has done during the update interval.

${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}

top_mem type num Same as ${top} except sorted by memory usage instead of CPU usage.

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

top_time type num Same as ${top} except sorted by total CPU time instead of current CPU usage.

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

totaldown [network_interface] Total download volume after Conky started. May overflow at 4GiB on Linux with 32-bit architecture.

${totaldown eth0}

totalup [network_interface] Total upload volume after Conky started. May overflow at 4GiB on Linux with 32-bit architecture.

${totalup eth0}

trashed_mails [mail_directory] Number of mails marked as trashed in the specified mailbox or mail spool if not. Only maildir type mailboxes are supported, mbox type will return -1.
tztime [timezone [format]] Local time for specified timezone. The timezone argument is specified in similar fashion as TZ environment variable. For hints, look in /usr/share/zoneinfo. See Time Format String Variables below for more information about the optional format codes.

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

gid_name gid_number Name of group with this gid.

${gid_name 1000}

uid_name uid_number Username of user with this uid.

${uid_name 1000}

unflagged_mails [mail_directory] Number of mails not marked as flagged in the specified mailbox or mail spool if not. Only maildir type mailboxes are supported, mbox type will return -1.
unforwarded_mails [mail_directory] Number of mails not marked as forwarded in the specified mailbox or mail spool if not. Only maildir type mailboxes are supported, mbox type will return -1.
unreplied_mails [mail_directory] Number of mails not marked as replied in the specified mailbox or mail spool if not. Only maildir type mailboxes are supported, mbox type will return -1.
unseen_mails [mail_directory] Number of new or unseen mails in the specified mailbox or mail spool if not. Only maildir type mailboxes are supported, mbox type will return -1.
updates Shows the number of times Conky has updated the display since it started. Mainly used for debugging.

${updates}

upspeed [network_interface] Upload speed in suitable IEC (International Electrotechnical Commission) units.

${upspeed eth0}

upspeedf [network_interface] Upload speed in KiB with one decimal place.

${upspeedf eth0}

upspeedgraph [network_interface] [height][,width] [gradient color 1] [gradient color 2] [scale] [-t] [-l] Upload speed graph. Colors are defined in RGB hexadecimal. If scale is non-zero, it becomes the scale for the graph. Uses a logarithmic scale (to see small numbers) when you use the -l switch. Takes the switch '-t' to use a temperature gradient, which makes the gradient values change depending on the amplitude of a particular graph value (try it and see).

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

uptime Uptime is the time elapsed since boot including seconds.

${uptime}

uptime_short Uptime in a shorter format without seconds.

${uptime_short}

user_names Lists the names of the users logged in.

${user_names}

user_number Number of users logged in.

${user_number}

user_terms Lists the consoles in use.

${user_terms}

user_times Lists how long users have been logged in for.

${user_times}

user_time console Lists how long the user for the given console has been logged in for
utime [format] Display time in UTC (universal coordinate time). See Time Format String Variables below for more information about the optional format codes.

${utime %T}

voffset [pixels] Change vertical offset by N pixels. Negative values cause text to overlap. See also ${offset}.

${voffset -16}

voltage_mv [cpu_number] Returns CPU #n's voltage in mV. CPUs are counted from 1. If omitted, the parameter defaults to 1.
voltage_v [cpu_number] Returns CPU #n's voltage in V. CPUs are counted from 1. If omitted, the parameter defaults to 1.
weather URI locID data_type [interval_in_minutes] Download, parse and display METAR data. For the URI. There are two possibilities:
  • 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.

weather_forecast URI locID day data_type [interval_in_minutes] Download, parse and display weather forecast data for a given day. Daytime only.

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).

data_type must be one of the following:
  • 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.

wireless_ap [network_interface] Wireless access point MAC address. Linux only.

${wireless_ap wlan0}

wireless_bitrate [network_interface] Wireless bitrate (ie 11 Mb/s). Linux only.

${wireless_bitrate wlan0}

wireless_essid [network_interface] Wireless access point ESSID. Linux only.

${wireless_essid wlan0}

wireless_link_bar [height][,width] [network_interface] Wireless link quality bar. Linux only.

${wireless_link_bar 10,60 wlan0}

wireless_link_qual [network_interface] Wireless link quality. Linux only.

${wireless_link_qual wlan0}

wireless_link_qual_max [network_interface] Wireless link quality maximum value. Linux only.

${wireless_link_qual_max wlan0}

wireless_link_qual_perc [network_interface] Wireless link quality in percents. Linux only.

${wireless_link_qual_perc wlan0}

wireless_mode [network_interface] Wireless mode. Managed, Ad-Hoc, Master. Linux only.

${wireless_mode wlan0}

words textfile Displays the number of words in the given file.

${words ~/example.txt}

X Multimedia System (XMMS) Audio Player
xmms2_album Album in current XMMS2 song.

${xmms2_album}

xmms2_artist Artist in current XMMS2 song.

${xmms2_artist}

xmms2_bar [height][,width] Bar of XMMS2's progress
xmms2_bitrate Bitrate of current song.

${xmms2_bitrate}

xmms2_comment Comment in current XMMS2 song.

${xmms2_comment}

xmms2_date Returns song's date.

${xmms2_date}

xmms2_duration Duration of current song.

${xmms2_duration}

xmms2_elapsed Song's elapsed time.

${xmms2_elapsed}

xmms2_genre Genre in current XMMS2 song.

${xmms2_genre}

xmms2_id XMMS2 id of current song.

${xmms2_id}

xmms2_percent Percent of song's progress.

${xmms2_percent}

xmms2_playlist Returns the XMMS2 playlist.

${xmms2_playlist}

xmms2_size Size of current song.

${xmms2_size}

xmms2_smart Prints the song name in either the form artist - title or file name, depending on whats available.

${xmms2_smart}

xmms2_status XMMS2 status. Playing, Paused, Stopped, or Disconnected.

${xmms2_status}

xmms2_timesplayed Number of times a song was played (presumably).

${xmms2_timesplayed}

xmms2_title Title in current XMMS2 song.

${xmms2_title}

xmms2_tracknr Track number in current XMMS2 song.

${xmms2_tracknr}

xmms2_url Full path to current song.

${xmms2_url}

Time Format String Variables

The time format string may contain special character sequences called conversion specifications, each of which is introduced by a percent % character and terminated by some other character known as a conversion specifier character. All other character sequences are ordinary character sequences.

The characters of conversion specifications are CASE SENSITIVE and are replaced using the following variables. Everything in the format string that does not match one of these variables is shown as-is.

VariableExplanation
%aThe abbreviated weekday name according to the current locale.

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

%AThe full weekday name according to the current locale.

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

%bThe abbreviated month name according to the current locale.

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

%BThe full month name according to the current locale.

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

%cThe preferred date and time representation for the current locale.
%CThe century number as a 2-digit integer. [SU Note]
Year/100.
%dThe day of the month as a decimal number.
Range 01 to 31.
%DEquivalent to %m/%d/%y. For North Americans only. To avoid confusion in international context do not use this format. [SU Note]
%eLike %d the day of the month as a decimal number but a leading zero is replaced by a space. [SU Note]
%EModifier: use alternative format, see below. [SU Note]
%FEquivalent to %Y-%m-%d also known as the ISO 8601 date format.
%GThe ISO 8601 week-based year [see Week Notes] with century as a decimal number. The 4-digit year corresponding to the ISO week number. See %V. This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead. [TZ Note]
%gLike %G, but without century, that is, with a 2-digit year. [TZ Note]
Range 00-99.
%hEquivalent to %b. [SU Note]
%HThe hour as a decimal number using a 24-hour clock.
Range 00 to 23.
%IThe hour as a decimal number using a 12-hour clock.
Range 01 to 12.
%jThe day of the year as a decimal number.
Range 001 to 366.
%kThe hour, 24-hour clock, as a decimal number. Single digits are preceded by a blank. See also %H. [TZ Note]
Range 0 to 23.
%lThe hour, 12-hour clock, as a decimal number. Single digits are preceded by a blank. See also %I. [TZ Note]
Range 1 to 12.
%mThe month as a decimal number
Range 01 to 12
%MThe minute as a decimal number
Range 00 to 59.
%nA newline character. [SU Note]
%OModifier: use alternative format, see below. [SU Note]
%pEither AM (Ante Meridiem) or PM (Post Meridiem) according to the given time value, or the corresponding strings for the current locale. 12:00 noon is PM and 12:00 midnight is AM.
%PLike %p but in lowercase: am or pm or a corresponding string for the current locale.
%rThe time in AM or PM notation. In the POSIX locale this is equivalent to %I:%M:%S %p. [SU Note]
%RThe time in 24-hour notation, same as %H:%M. [SU Note] For a version including the seconds see %T below.
%sThe number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). [TZ Note]
%SThe second as a decimal number with max value of 61. The 62 second range allows for the theoretical possibility of a minute that included a double leap second. There never has been such a minute.
Range 00 to 61.
%tThe tab character. [SU Note]
%TThe time in 24-hour notation, %H:%M:%S. [SU Note]
%uThe day of the week as a decimal, range 1 to 7, Monday being 1. See also %w. [SU Note]
%UThe week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also %V and %W.
%VThe ISO 8601 week number [see Week Notes] of the current year as a decimal number. See also %U and %W. [SU Note]
Range 01 to 53.
%wThe day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.
%WThe week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01.
%xThe preferred date representation for the current locale without the time.
%XThe preferred time representation for the current locale without the date.
%yThe year as a two digit decimal number without a century.
Range 00 to 99.
%YThe year as a four digit decimal number including the century.
Range 0000 to 9999.
%zThe +hhmm or -hhmm numeric timezone showing the hour and minute offset from UTC. [SU Note]
%ZThe timezone or name or abbreviation.
%+The date and time in date(1) format. [TZ Note]
%a, %d %b %Y %T %zRFC 2822-compliant date format (with an English locale for %a and %b)
%a, %d %b %y %T %zRFC 822-compliant date format (with an English locale for %a and %b)
%%The literal percent % character.

Installing and Starting Conky

This is not intended to be an exhaustive guide to getting Conky to run on every Linux distribution. Instead this is a quick guide how I got Conky running on most Ubuntu distributions. If you run into trouble help is often as close as the user support message board for your Linux distribution.

On most distributions you can install Conky with the Ubuntu Software Center, with the Synaptic Package Manager, or using this terminal command.

sudo apt-get install conky

The next step is to put a script in place to get Conky started when you log in. This requires two parts. The first is a Conky configuration file telling Conky what to show. If this part is missing a default information report is shown to at least let you know that things are working. The second is a script to call Conky and tell it where to find the configuration file. The following shows two examples, how to start Conky with a single configuration file and how to start Conky with more than one file. The second example shows how you can expanded this to call any number of Conky configuration files you want.

Start Conky with a single configuration file located in the .conky folder under your home directory.

#!/bin/bash
# this is a copy of the conky_start file located in /bin
conky -c ~/.conky/conkyrc1

If you want to have more than one Conky configuration file you can start multiple copies of Conky each with a different configuration file by adding a space followed by an ampersand to the end of all but the last Conky line.

#!/bin/bash
# this is a copy of the conky_start file located in /bin
conky -c ~/.conky/conkyrc1 &
conky -c ~/.conky/conkyrc2

After the conky_start file you want is created and located in the /bin folder the executable bit must be set to allow it to run.

sudo chmod +x /bin/conky_start

The last step is to tell Conky to automatically start when you log in. This can be done in Settings -> Session and Startup -> Application Autostart by adding a new item. The Name and Description can be whatever you want but the Command needs something extra.

The desktop can have a lot of different things happening at login and some of these overwrite your Conky display making it look like Conky is not working when in fact it is hidden behind something else. A good way around this is to delay calling Conky for a short while to give everything else a chance to run first. The following command waits 10 seconds (note the 10s part in the middle) before calling conky_start. This works well for me but add a little extra time if you have a slower computer or have a lot of things doing stuff on the desktop at login.

sh -c "sleep 10s; conky_start"

This is all you need for the most simplistic information display. Most people want something more specific to their configuration and formatted to be more pleasing which is where customization comes into the picture. Using the information on this page you can create something that is unique and completely customized to your exact hardware and software setup but that is a big step to take starting from scratch. Instead it helps to start with a Conky config that someone else created and use that as a starting place for tinkering and tweaking.

Conky Themes

Many Conky themes are available that can be downloaded and used often without any modification. Most Conky themes are designed for Linux desktop environments but some BSD themes are available that use slightly different commands and may not work the same on Linux desktops. Start your search at places like gnome-look.org and deviantart.com. Some themes may use Lua scripts and other external support programs. If this is the case you may need to edit the theme a little bit or just put the files where the theme wanted them originally. I put all the Conky theme and configuration files inside the ~/.conky/ directory below my home directory just to keep everything organized.

If you just want to install a simple Conky config file without special graphics or anything then you can just copy the default file to ~/.conky/ and save it as conkyrc1. Some Conky tutorials suggest to copy the .conkyrc into your home folder. This works but it is best to keep Conky related things organized together for easier editing. To manually start Conky using your new theme, run the following command from a terminal.

conky -c ~/.conky/conkyrc1

It is a good idea at this point to log out and log back in to test if Conky starts correctly.

Notes:

Single UNIX Specification

Some conversion specifications can be modified by preceding the conversion specifier character by the E or O (zero) modifier to indicate an alternative format should be used. If the alternative format or specification does not exist for the current locale, the behavior is as if the unmodified conversion specification were used. The Single UNIX (SU) Specification mentions %Ec, %EC, %Ex, %EX, %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy, where the effect of the O modifier is to use alternative numeric symbols (say, roman numerals), and that of the E modifier is to use a locale-dependent alternative representation.

ISO 8601 week dates

%G, %g, and %V yield values calculated from the week-based year defined by the ISO 8601 standard. In this system, weeks start on a Monday, and are numbered from 01, for the first week, up to 52 or 53, for the last week. Week 01 is the first week where

When three or fewer days of the first calendar week of the new year fall within that year, then the ISO 8601 week-based system counts those days as part of week 53 of the preceding year. For example, 1 January 2010 was a Friday, meaning that just three days of that calendar week fall in 2010. Thus, the ISO 8601 week-based system considers these days to be part of week 53 (%V) of the year 2009 (%G) ; week 01 of ISO 8601 year 2010 started on Monday, 4 January 2010.

Time Zone

All time values are based on the time zone of the local machine unless otherwise noted. The local time zone can change if Daylight Saving Time or Summer Time changes are observed on the local machine. Times that specifically reference UTC are not effected by the local time zone.

About Conky

Conky is a system monitor primarily for environments running the X Window System. Unlike other desktop information display methods using independently running scripts or programs (i.e. widgets), Conky is able to do most information gathering and display tasks on a single CPU thread which makes it amazingly light weight even when showing a lot of information. It is also very configurable. Conky can display just about anything, either on your root desktop, in a terminal or in its own window. Not only does Conky have many built-in objects it can also display just about any piece of information in a textual or graphical way.

Conky has many built in objects including support for a plethora of operating system statistics, built in IMAP and POP3 support, built in support for many popular music players, and much much more. Conky can display this information either as formatted text or using simple progress bars and graphs all with different fonts and colors. Light weight Lua scripts can be used to extend Conky in many ways including adding the ability to display custom graphics if desired.

Conky licensed under the GNU General Public License (GPL) except where noted differently.

Conky Tips and Tricks

Conky already has many ways to directly access and display system information internally but sometimes you need something more. Here are some examples of how to use common external tools to bridge the information gap until Conky catches up.

Show all connected storage devices dynamically updated.

A very useful tool for hot-connect things like USB storage. This uses a template to both make the execpi call easier to understand and to make each device display more consistent with single point editing for changes as needed. The template must appear before the TEXT line in your configuration file.

# Format the storage information the same way for every device. Parameters: [human name] [path]
template3 \1 [${fs_size \2} ${fs_type \2}]${alignr}${fs_used \2} used ${fs_bar 10,60 \2}\n${alignr}${voffset -15}${fs_used_perc \2}%\nMount=${color2}\2

TEXT
# show info about connected drives
${execpi 60 df -h --output=source,target | grep '^/dev/' | cut --characters=6- | sed 's/^/\$\{template3 /;s/$/\}/'}

Show name of current Ubuntu desktop variant.

Ubuntu MATE and Ubuntu GNOME only show MATE or GNOME receptively.

# Shows Kubuntu, Xubuntu, Lubuntu, etc.
${execi 60000 env | grep '^DESKTOP_SESSION' | cut -d'=' -f2-}

Show attached USB devices.

This the number of USB devices that are not hubs currently connected to your system and the name each device reports to the system. Very handy to see if your USB mouse or keyboard are connected and recognized. Updated once every 5 seconds for lower CPU load.

# Show number of USB connected items that are not hubs
USB Devices Attached ${execpi 5 lsusb | grep -iv 'hub' | cut --fields=7- --delimiter=' ' | wc -l}
# Get the name of each item
${execpi 5 lsusb | grep -iv 'hub' | cut --fields=7- --delimiter=' '}

Show all available Ethernet network interfaces.

This uses a template to make the execpi call easier to understand and to make each interface display more consistent with single point editing for changes as needed. The template must appear before the TEXT line in your configuration file. Works well for USB connected Ethernet network interfaces that are not connected all the time.

Works for both eth* and enp* interface names.

# Ethernet interface info
template7 ${if_up \1}Ethernet (\1) ${alignr}IP ${addr \1}\nUp [${totalup}]${alignr}${upspeedgraph \1 10,120 884400 995500 -l}\n${voffset -15}${alignr}${upspeed \1} \nDn [${totaldown}]${alignr}${downspeedgraph \1 10,120 884400 995500 -l}\n${voffset -15}${alignr}${downspeed \1} ${else}Ethernet (\1)${alignr}not connected${endif}

TEXT
# Show available Ethernet interface(s)
${execpi 60 cat /proc/net/dev | grep 'eth' | cut --fields=-1 --delimiter=':' | sed 's/^/\$\{template7 /;s/$/\}/'}
${execpi 60 cat /proc/net/dev | grep 'enp' | cut --fields=-1 --delimiter=':' | sed 's/^/\$\{template7 /;s/$/\}/'}
# The following line is the same as the above two if both are needed on your system.
#${execpi 60 cat /proc/net/dev | grep -e 'eth' -e 'enp' | cut --fields=-1 --delimiter=':' | sed 's/^/\$\{template7 /;s/$/\}/'}

Show all available wireless network interfaces.

This uses a template to make the execpi call easier to understand and to make each interface display more consistent with single point editing for changes as needed. The template must appear before the TEXT line in your configuration file. Works well for USB connected wireless network interfaces that are not connected all the time.

# Wifi interface info
template8 ${if_up \1}IP ${addr \1} ${alignr}Gateway ${gw_iface}\nEssid ${wireless_essid \1}\nSignal ${wireless_link_qual \1}: ${wireless_link_qual_perc \1}% ${alignr}${wireless_mode \1} Rate ${wireless_bitrate \1}\nUp [${totalup \1}] ${alignr}${upspeedgraph \1 10,120 884400 995500 -l}\n${voffset -15}${alignr}${upspeed \1} \nDn [${totaldown \1}]${alignr}${downspeedgraph \1 10,120 884400 995500 -l}\n${voffset -15}${alignr}${downspeed \1} ${else}WiFi (\1)${alignr}not connected${endif}

TEXT
# Show available wireless interface(s)
${execpi 60 cat /proc/net/dev | grep 'wlan' | cut --fields=-1 --delimiter=':' | sed 's/^/\$\{template8 /;s/$/\}/'}