Last updated 20210416 by Casey Sprangel, IFX Group. Conky and this document are licensed under GNU General Public License. This page is self contained and may be saved locally for off-line reference. The latest version is at www.ifxgroup.net/conky.htm
A different background color is used for each major section of this document as a visual clue when you scroll or search. Every command or variable in the first column is linked to make it easier to direct attention at a specific section of this document if needed. This also makes cross reference navigation possible.
Command line options override settings defined in configuration file. Command line options are case sensitive.
Option (case sensitive) | Explanation |
---|---|
-v | -V | --version | Prints Conky version with a list of compiled in options then exits. conky --version |
-q | --quiet | Run Conky in quiet mode with no output in the terminal used to start conky. The default is to show errors, warnings, and progress information in the terminal. conky --quiet |
-D | -DD | --debug | Debugging output with two detail levels. -Dis level one detail, -DDfor more detail. conky --debug |
-a | --alignment=<position> | Text alignment on screen. Syntax: {top,bottom,middle}_{left,right,middle} or none. Can also be abbreviated with first characters of position. See alignment command. conky --alignment=top_right |
-b | --double-buffer | Use double buffering. This helps eliminate flickerby using more memory. See double_buffer command. conky --double-buffer |
-c | --config=<file_name> | Config file to load instead of the default. The default configuration file location is conky -c conkyrc.conf |
-C | --print-config | Print internal default config to stdout. This is useful when starting from scratch. conky --print-config |
-d | --daemonize | Daemonize Conky by forking process to background. See background command. conky --daemonize |
-f | --font=<font_name> | Set default font to use. Font name must be quoted if it contains spaces. See font command. conky -f Ubuntu |
-h | --help | Prints command line help and exits. conky --help |
-o | --own-window | Create own window to draw. See own_window command. conky --own-window |
-s | --for-scripts 'string' | Prints the string of text to standard output and exits. This is useful when using Conky in scripts. TEXT has to be enclosed by single quotes. conky --for-scripts 'Your uptime is: $uptime' |
-S | --stdin-config | Read configuration from stdin (standard input). cat conkyrc.conf | conky --stdin-config |
-t | --text='string' | Text to render. The text must be in single quotes. conky --text=' $uptime ' |
-p | --pause=<seconds> | Time to pause before actually starting Conky. conky --pause=10 |
-u | --interval=<seconds> | Update interval in seconds. See update_interval command. conky --interval=2 |
-w | --window-id=<win_id_number> | Window id to draw. conky -w 4101 |
-X | --display=<display_number> | X11 display to use. conky --display=2 |
-x <pixels> | X position from left edge of screen in pixels. Negative numbers are position from right edge. See gap_x command. conky -x 150 |
-y <pixels> | Y position from top edge of screen in pixels. Negative numbers are position from bottom edge. See gap_y command. conky -y 20 |
-i <COUNT> | Number of times to update Conky before exit. See total_run_times command. conky -i 300 |
The Conky configuration file(s) can be placed anywhere you want. The default is
(in your home directory) or $HOME/.config/conky/conky.conf
(on most systems sysconfdir is /etc). The configuration is defined in a text file with two main parts divided by a line with the word ${sysconfdir}/conky/conky.conf
TEXT
.
This section describes commands that appear above the TEXT
command in the Conky configuration file.
Variable | Explanation |
---|---|
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 |
append_file | Append the file given as argument. append_file /home/user/.config/conky/common.conf |
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 |
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 Trueor Yesto 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.
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 10at 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 10at 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 hddtempto work. hddtemp_host 127.0.0.1 |
hddtemp_port | Port to use for hddtemp connections. Defaults to 7634. This is required for hddtempto work. hddtemp_port 7634 |
if_up_strictness | How strict should ${if_up} be when testing an interface for being connected? The value is one of the following choices:
if_up_strictness address |
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_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 Lua script(s) separated by spaces. lua_load ~/.config/conky/scripts/example.lua ~/.config/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_in front of it yourself. Both of the following lua functions are called with the function name; 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 widthcharacters 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.1before 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 stdoutstandard 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 NOthere 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.txtfor 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 desktopas another way to implement many of these hints implicitly. If you use own_window_type desktop |
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 |
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 fahrenheitor celsius. Default unit is degrees Celsius. temperature_unit celsius |
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.
template0 ${\1\2} |
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_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. # Tell Conky to run 10 times then exit. |
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.
A bar down the left side of some variables shows groups with a related purpose or function.
Variable/Arguments | 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_supplycontaining the state information. Conky tries ACand ADP1if 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 Addressif 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. ${alignc -5} |
|
alignr [number] |
Right-justify text. The optional number pads the right side with N spaces. ${alignr 2} |
|
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-lineor 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:ssor unknownif AC adapterstatus is on-line or charging. FreeBSD only. ${apm_battery_time} |
|
Audacious Audio Player | ||
audacious_bar [height][,width] |
Progress bar for current song. ${audacious_bar 10,20} |
|
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:SSformat. ${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. ${audacious_title 30} |
|
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_varsblink 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 stringin it's command line. ${cmdline_to_pid "demo"} |
|
color [color] |
Change drawing color to colorwhich 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:
${color red}This is Red |
|
colorN | Change drawing color to predefined color Nconfiguration option, where N is a digit between 0 and 9 inclusive; color0, color1, color2, color3, color4, color5, color6, color7, color8, color9. color8 f9cc00 |
|
combine var1 var2 |
Combines two lists into columns. The lines of var2 are added to the right of the lines of var1 separated by the character(s) that are put between var1 and var2.
${combine ${head /proc/cpuinfo 2} - ${head /proc/meminfo 1}} This gives as outputcpuinfo_line1 - meminfo_line1on line 1 and cpuinfo_line2 -on line 2. Combined variables can also be nested to place more variables next to each other. |
|
Conky Information | ||
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 Information | ||
cpu [cpu_Number] |
CPU usage in percents. For SMP machines, the optional CPU number can be provided as an argument. ${cpu cpu0}is the combined total usage, and ${cpu cpu#}where # is a positive whole number for individual CPUs. ${cpu cpu0}% Total |
|
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 cpu0 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 -lswitch uses a logarithmic scale to make small numbers more visible. The lower case T -tswitch enables temperature gradient to make the color values change depending on the amplitude of the CPU load. ${cpugraph cpu0 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. ${curl http://www.ifxgroup.net/conky.htm 1440} |
|
Desktop Information | ||
desktop | X-windows virtual desktop number or the message Not running in Xif this is the case. ${desktop} |
|
desktop_name | Name of the desktop on which Conky is running or the message Not running in Xif this is the case. ${desktop_name} |
|
desktop_number | Number of desktops or the message Not running in Xif this is the case. ${desktop_number} |
|
Disk Information | ||
disk_protect device |
Disk protection status, if supported. This may need a kernel-patch. Prints either frozenor 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 -lswitch uses a logarithmic scale to make small numbers more visible. The lower case T -tswitch 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 -lswitch uses a logarithmic scale to make small numbers more visible. The lower case T -tswitch 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 -lswitch uses a logarithmic scale to make small numbers more visible. The lower case T -tswitch 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} |
|
endif | Ends an ${if_*}block. ${if_existing ~/example.log} |
|
Entropy Information | ||
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. | |
External Commands | ||
exec command |
Executes a shell command and displays the output in Conky.
${exec cat /etc/debian_version} May cause conky to run slow. |
|
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. May cause conky to run slow. | |
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. May cause conky to run slow. | |
execgraph [-t] [-l] command |
Same as ${execbar} but graphs values. Uses a logarithmic scale when the log option, lower case L -lswitch 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_sizeconfig setting. Takes the switch -tto 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 ( ). May cause conky to run slow. |
|
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} May cause conky to run slow. |
|
execibar interval command |
Same as execbar except with an interval. May cause conky to run slow. | |
execigauge interval command |
Same as execgauge but takes an interval arg and gauges values. May cause conky to run slow. | |
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 (). May cause conky to run slow. |
|
execp command |
Executes a shell command and displays the output in Conky. 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. ${execp cat /etc/debian_version} May cause conky to run slow. |
|
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.
${execpi 300 cat /etc/debian_version} May cause conky to run slow. |
|
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.
${format_time "\h:\m:\s"} |
|
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_systemis 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 numberfrom 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. See also ${offset}. ${goto 10} |
|
gw_iface | Displays the default route's interface or multipleor noneaccordingly. ${gw_iface} |
|
gw_ip | Displays the default gateway's IP or multipleor noneaccordingly. ${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 deviceparameter 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_checkupdate. 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. See ${tail} for end of file. ${head ~/sample.log 5 3} |
|
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 deviceis the device name and may be omitted if you have only one hwmon device. Parameter type is one of the following.
/sys/class/hwmon/on your local computer. The optional arguments factorand offsetallow 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/i8ktranslated 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/i8ktranslated 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/i8ktranslated 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. Numberhas 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 mastervolume, 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 startand stopare converted. ${iconv_start UTF-8 ISO_8859-1} |
|
iconv_stop | Stop iconv codeset conversion. ${iconv_start UTF-8 ISO_8859-1} |
|
Conditionals | ||
if_empty [var] |
If Conky variable VAR is empty, display everything between ${if_empty} and the matching ${endif}. ${if_empty var} |
|
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"} |
|
if_gw | If there is at least one default gateway, display everything between ${if_gw} and the matching ${endif}. ${if_gw} |
|
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:
${if_match "${tcp_portmon 1 65534 rip eth0}">""} |
|
if_mixer_mute [mixer] |
If mixer exists, display everything between ${if_mixer_mute}and the matching ${endif}. If no mixer is specified, Volis used. ${if_mixer_mute} |
|
if_mounted [mountpoint] |
If MOUNTPOINT is mounted, display everything between ${if_mounted}and the matching ${endif}. ${if_mounted /media/thumbdrive} |
|
if_mpd_playing | If mpd is playing or paused, display everything between ${if_mpd_playing}and the matching ${endif}. ${if_mpd_playing} |
|
if_running [-x] process_name |
If PROCESS is running, display everything between the ${if_running}and the matching ${endif}. This uses the pidofcommand, so the -x switch is also supported.
${if_running firefox} ... ${endif} |
|
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} |
|
if_up [interface] |
If the named interfaceexists and is up (according to the if_up_strictness setting), display everything between ${if_up}and the matching ${endif}. ${if_up eth0} |
|
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} foo25% of the time followed by bar25% 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} |
|
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 renderscheeseburger.jpgcentered 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 host username password [-i interval (in seconds)] [-f "folder"] [-p port] [-e "command"] [-r retries] |
Displays the number of messages in your global IMAP inbox by default. You can define individual IMAP inboxes separately by passing the folder name with the -fargument. Arguments are:
${imap_messages imap.example.com user *} |
|
imap_unseen host username password [-i interval (in seconds)] [-f "folder"] [-p port] [-e "command"] [-r retries] |
Displays the number of messages in your global IMAP inbox by default. You can define individual IMAP inboxes separately by passing the folder name with the -fargument. Arguments are:
${imap_unseen imap.example.com user *} |
|
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 hdaor 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. See words. ${lines ~/example.txt} |
|
loadavg [1|2|3] |
System load average, 1is for past 1 minute, 2for past 5 minutes and 3for 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 -lswitch. Takes the switch -tto 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_64or 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.
${mboxscan -n 10 "/home/user/some box"} |
|
Memory Information | ||
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. ${memgauge 10,120} |
|
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:
${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 Xif this is the case. ${monitor} |
|
monitor_number | Number of monitors or the message Not running in Xif 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_bar 10,20} |
|
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 Onor Off. ${mpd_random} |
|
mpd_repeat | Repeat status Onor Off. ${mpd_repeat} |
|
mpd_smart [max_length] |
Shows the song name in either the form artist - titleor file name, depending on what is available. ${mpd_smart 30} |
|
mpd_status | Playing, stopped, et cetera. ${mpd_status} |
|
mpd_title [max_length] |
Title of current MPD song. ${mpd_title 30} |
|
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 -sshell command. ${nodename_short} |
|
nvidia item |
Nvidia graphics card support using the XNVCtrl library. Each itemoption can be shortened to the least significant part as highlighted below. Temperatures are shown as float, all other values as integer.
${nvidia threshold} |
|
offset [pixels] |
Move text over by the given number of pixels to the right. Negative values move to the left. See also See also ${goto} ${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:
${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 an environment-var of the process. ${pid_environ 2649} |
|
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 priorityin 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 RSDZTWrepresenting the state of the process where
${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 markof 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 on Linux kernel 2.6 and higher. Parameter dev may be omitted if you have only one platform device. Platform type options:
factorand offsetallow 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 host username password [-i interval] [-p port] [-e "command"] [-r retries] |
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:
|
|
pop3_used host username password [-i interval] [-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.
|
|
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 |
|
processes | Total processes including both sleepingand runningstates. ${processes} |
|
read_tcp [host] port |
Connects to a tcp port on a host. The default host localhostreads 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.
${rss http://user:pass@example.com/news.rss 60 feed_title} |
|
running_processes | Running processes (not sleeping) on Linux kernel 2.6 or higher. ${running_processes} |
|
running_threads | Number of running (runnable) threads. Linux only. ${running_threads} |
|
scroll length [step] text |
Scroll textby stepcharacters showing lengthnumber of characters at the same time. The text may also contain Conky variables. Stepis optional and defaults to 1if 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 lengthnumber of spaces. ${scroll 30 ${audacious_title}} |
|
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 (FILENAME) |
When using smapi, display contents of the /sys/devices/platform/smapi directory. ARGS are one of the following:
|
|
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_spacerconfiguration 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 spacenumber is the number of pixels for the gaps. ${stippled_hr 5} |
|
Swap Information | ||
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, Linuxfor example. ${sysname} |
|
tab [width[, start]] |
Puts a tab of the specified width, optionally starting from column start. The unit is pixels for both arguments. ${tab 30} |
|
tail logfile lines [next_check] |
Displays last linesnumber of lines of supplied text file. The file is checked every next_checktimes 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. See ${head} for top of file. ${tail ~/example.txt 5 3} |
|
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 itemnames can be used for monitoring.
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} | ||
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. ${texeci 600 ~/work.sh} |
|
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 sizeis a number followed by a size-unit (kilobyte,mb,GiB,...) it is converted to bytes, otherwise the sizeparameter is shown unchanged. ${to_bytes ${mem}} |
|
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:
numparameter 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_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_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_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} |
|
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 |
|
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. ${user_time 2} |
|
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_mv 1} |
|
voltage_v [cpu_number] |
Returns CPU #n's voltage in V. CPUs are counted from 1. If omitted, the parameter defaults to 1. ${voltage_v 1} |
|
weather URI locID data_type [interval_in_minutes] |
Download, parse and display METAR data. For the URI. There are two possibilities:
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:
'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 locID, see day is a number from 0 (today) to 4 (3 days after tomorrow). data_type must be one of the following:
'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 Information | ||
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. See lines. ${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_bar 10,20} |
|
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 - titleor 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} |
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.
Variable | Description |
---|---|
%a | The abbreviated weekday name according to the current locale. Mon, Tue, Wed, Thu, Fri, Sat, Sun |
%A | The full weekday name according to the current locale. Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday |
%b | The abbreviated month name according to the current locale. Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec |
%B | The full month name according to the current locale. January, February, March, April, May, June, July, August, September, October, November, December |
%c | The preferred date and time representation for the current locale. |
%C | The century number as a 2-digit integer. [SU Note] Year/100. |
%d | The day of the month as a decimal number. Range 01 to 31. |
%D | Equivalent to %m/%d/%y. For North Americans only. To avoid confusion in international context do not use this format. [SU Note] |
%e | Like %d the day of the month as a decimal number but a leading zero is replaced by a space. [SU Note] |
%E | Modifier: use alternative format, see below. [SU Note] |
%F | Equivalent to %Y-%m-%d also known as the ISO 8601 date format. |
%G | The 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] |
%g | Like %G, but without century, that is, with a 2-digit year. [TZ Note] Range 00-99. |
%h | Equivalent to %b. [SU Note] |
%H | The hour as a decimal number using a 24-hour clock. Range 00 to 23. |
%I | The hour as a decimal number using a 12-hour clock. Range 01 to 12. |
%j | The day of the year as a decimal number. Range 001 to 366. |
%k | The hour, 24-hour clock, as a decimal number. Single digits are preceded by a blank. See also %H. [TZ Note] Range 0 to 23. |
%l | The hour, 12-hour clock, as a decimal number. Single digits are preceded by a blank. See also %I. [TZ Note] Range 1 to 12. |
%m | The month as a decimal number Range 01 to 12 |
%M | The minute as a decimal number Range 00 to 59. |
%n | A newline character. [SU Note] |
%O | Modifier: use alternative format, see below. [SU Note] |
%p | Either 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 PMand 12:00 midnight is AM. |
%P | Like %p but in lowercase: amor pmor a corresponding string for the current locale. |
%r | The time in AMor PMnotation. In the POSIX locale this is equivalent to %I:%M:%S %p. [SU Note] |
%R | The time in 24-hour notation, same as %H:%M. [SU Note] For a version including the seconds see %Tbelow. |
%s | The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). [TZ Note] |
%S | The 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. |
%t | The tab character. [SU Note] |
%T | The time in 24-hour notation, %H:%M:%S. [SU Note] |
%u | The day of the week as a decimal, range 1 to 7, Monday being 1. See also %w. [SU Note] |
%U | The 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. |
%V | The 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. |
%w | The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u. |
%W | The 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. |
%x | The preferred date representation for the current locale without the time. |
%X | The preferred time representation for the current locale without the date. |
%y | The year as a two digit decimal number without a century. Range 00 to 99. |
%Y | The year as a four digit decimal number including the century. Range 0000 to 9999. |
%z | The +hhmm or -hhmm numeric timezone showing the hour and minute offset from UTC. [SU Note] |
%Z | The timezone or name or abbreviation. |
%+ | The date and time in date(1) format. [TZ Note]
|
%% | The literal percent %character. |
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-all
The next step is to put a script in place to get Conky started when you log in. This uses two parts.
The first is a Conky configuration file telling Conky what to show. If this file is missing the default
(in your home directory) or $HOME/.config/conky/conky.conf
(on most systems, sysconfdir is /etc) is used to let you know Conky is installed and working.${sysconfdir}/conky/conky.conf
The second is a script to call Conky and tell it where to find your custom 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.
The following bash script can be used to start Conky with a single configuration /.config/conky/conky.conf
in your home directory.
Open a text editor, paste the following text, and save it with the name
. conky_start.sh
#!/bin/bash
# this is a copy of the conky_start.sh file located in /bin
conky -c $HOME/.config/conky/conky.conf
After the conky_start.sh
file is created the executable bit must be set to allow it to run.
sudo chmod +x /bin/conky_start.sh
Next move the file to the /bin
folder.
sudo mv conky_start.sh /bin
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.sh file located in /bin
conky -c $HOME/.config/conky/conky.conf &
conky -c $HOME/.config/conky/conky2.conf
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 like the wallpaper. 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 30 seconds (note the 30s
part in the middle) before calling conky_start.sh. This works well for me but you may need to add a little extra time on slower computers or if the desktop is extra busy at login.
sh -c "sleep 30s; conky_start.sh"
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 it as your starting place for tinkering and tweaking.
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 /.config/conky/
directory below my home directory to keep everything organized and out of the way.
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 ~/.config/conky/conky.conf
. Some Conky tutorials suggest to put the conky.conf
in your home folder. This works but it is often best to keep Conky related things organized together for easier editing and out of the way the rest of the time. To manually start Conky using your new theme, run the following command from a terminal.
conky -c ~/.config/conky/conky.conf
It is a good idea at this point to log out and log back in to test if Conky starts correctly.
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.
%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.
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.
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.
Ubuntu versions with multiple words only show the last word. For example Ubuntu MATE
and Ubuntu GNOME
only show MATE
or GNOME
receptively.
# Shows Kubuntu, Lubuntu, Ubuntu, Xubuntu, etc.
${execi 60000 env | grep '^DESKTOP_SESSION' | cut -d'=' -f2-}
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/$/\}/'}
Display the currently connected USB devices (not hubs) and the name each device reports to the system. This is very handy to see if a newly attached USB device claims to be something unexpected such as a thumbdrive showing up as a mouse, keyboard, or network interface. 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=' '}
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 et*
and en*
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 'et' | cut --fields=-1 --delimiter=':' | sed 's/^/\$\{template7 /;s/$/\}/'}
${execpi 60 cat /proc/net/dev | grep 'en' | 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/$/\}/'}
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/$/\}/'}
The following is a short list of things to check when Conky shows on the desktop with a black box background.
Settings -> Settings Manager -> Window Manager Tweaks -> Compositor -> Enable Display Compositing
own_window yes
own_window_class Conky
own_window_type desktop
own_window_hints undecorated,sticky,skip_taskbar,skip_pager,below
own_window_argb_visual yes
own_window_argb_value 255
own_window_transparent yes
/etc/X11/xorg.conf
to update or include the following section. Section "Module" Load "dbe" EndSection
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. 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 dynamic graphics.
Conky is licensed under the GNU General Public License (GPL).
The latest version of Conky is available at https://github.com/brndnmtthws/conky