1conky(1) conky(1)
2
6 conky - A system monitor for X originally based on the torsmo code, but
7 more kickass. It just keeps on given'er. Yeah.
8
10 conky [ options ]
11
13 Conky is a system monitor for X originally based on torsmo. Since its
14 inception, Conky has changed significantly from its predecessor, while
15 maintaining simplicity and configurability. Conky can display just
16 about anything, either on your root desktop or in its own window. Not
17 only does Conky have many built-in objects, it can also display just
18 about any piece of information by using scripts and other external pro‐
19 grams.
20 Conky has more than 250 built in objects, including support for a
22 plethora of OS stats (uname, uptime, CPU usage, mem usage, disk usage,
23 "top" like process stats, and network monitoring, just to name a few),
24 built in IMAP and POP3 support, built in support for many popular music
25 players (MPD, XMMS2, BMPx, Audacious), and much much more. Conky can
26 display this info either as text, or using simple progress bars and
27 graph widgets, with different fonts and colours.
28 We are always looking for help, whether its reporting bugs, writing
30 patches, or writing docs. Please use the facilities at SourceForge to
31 make bug reports, feature requests, and submit patches, or stop by
32 #conky on irc.freenode.net if you have questions or want to contribute.
33 Thanks for your interest in Conky.
35
37 For users compiling from source on a binary distro, make sure you have
38 the X development libraries installed (Unless you configure your build
39 without X11). This should be a package along the lines of "libx11-dev"
40 or "xorg-x11-dev" for X11 libs, and similar "-dev" format for the other
41 libs required (depending on your build options). You should be able to
42 see which extra packages you need to install by reading errors that you
43 get from running `cmake'. The easiest way to view the available build
44 options is to run `ccmake' or `cmake-gui' from the source tree, but be
45 careful when disabling certain features as you may lose desired func‐
46 tionality. E.g., with BUILD_MATH disabled you won't get errors but log‐
47 arithmic graphs will be normal graphs and gauges will miss their line.
48 Conky has (for some time) been available in the repositories of most
50 popular distributions. Here are some installation instructions for a
51 few:
52 Gentoo users -- Conky is in Gentoo's Portage... simply use "emerge
54 app-admin/conky" for installation.
55 Debian, etc. users -- Conky should be in your repositories, and can be
57 installed by doing "aptitude install conky".
58 Example to compile and run Conky with default components (note that
60 some build options may differ for your system):
61 cmake -D CMAKE_INSTALL_PREFIX:string=/usr .
63 make
65 make install # Optional
67 src/conky
69 Conky has been tested to be compatible with C99 C and C++0x C++, howev‐
71 er it has not been tested with anything other than gcc, and is not
72 guaranteed to work with other compilers.
73 TIP: Try configuring Conky with `ccmake' or `cmake-gui' instead of just
75 `cmake'.
76
78 Conky is generally very good on resources. That said, the more you try
79 to make Conky do, the more resources it is going to consume.
80 An easy way to force Conky to reload your ~/.config/conky/conky.conf:
82 "killall -SIGUSR1 conky". Saves you the trouble of having to kill and
83 then restart. You can now also do the same with SIGHUP.
84
86 Command line options override configurations defined in configuration
87 file.
88 -a | --alignment= ALIGNMENT
90 Text alignment on screen, {top,bottom,middle}_{left,right,mid‐
91 dle} or none. Can also be abbreviated with first chars of posi‐
92 tion, ie. tr for top_right. Only available with build flag
93 BUILD_X11 enabled.
94 -b | --double-buffer
97 Use double buffering (eliminates "flicker"). Only available with
98 build flag BUILD_X11 enabled.
99 -c | --config= FILE
102 Config file to load instead of $HOME/.config/conky/conky.conf
103 -C | --print-config
106 Print builtin default config to stdout. See also the section EX‐
107 AMPLES for more information. Only available with build flag
108 BUILD_BUILTIN_CONFIG enabled.
109 -d | --daemonize
112 Daemonize Conky, aka fork to background.
113 -D | --debug
116 Increase debugging output, ie. -DD for more debugging.
117 -f | --font= FONT
120 Font to use. Only available with build flag BUILD_X11 enabled.
121 -h | --help
124 Prints command line help and exits.
125 -i COUNT
128 Number of times to update Conky (and quit).
129 -o | --own-window
132 Create own window to draw. Only available with build flag
133 BUILD_X11 enabled.
134 -p | --pause= SECONDS
137 Time to pause/wait before actually starting Conky.
138 -q | --quiet
141 Run Conky in 'quiet mode' (ie. no output).
142 -t | --text= TEXT
145 Text to render, remember single quotes, like -t ' $uptime '
146 -u | --interval= SECONDS
149 Update interval.
150 -v | -V | --version
153 Prints version, build information and general info. Exits after
154 printing.
155 -w | --window-id= WIN_ID
158 Window id to draw. Only available with build flag BUILD_X11 en‐
159 abled.
160 -x X_COORDINATE
163 X position
164 -x X_COORDINATE
167 X position
168 -X | --display= DISPLAY
171 X11 display to use. Only available with build flag BUILD_X11 en‐
172 abled.
173 -y Y_COORDINATE
176 Y position
177
180 Default configuration file location is $HOME/.config/conky/conky.conf
181 or ${sysconfdir}/conky/conky.conf. On most systems, sysconfdir is /etc,
182 and you can find the sample config file there (/etc/conky/conky.conf).
183 You might want to copy it to $HOME/.config/conky/conky.conf and then
185 start modifying it. Other configs can be found at http://conky.sf.net/
186 alignment
188 Aligned position on screen, may be top_left, top_right, top_mid‐
189 dle, bottom_left, bottom_right, bottom_middle, middle_left, mid‐
190 dle_middle, middle_right, or none (also can be abreviated as tl,
191 tr, tm, bl, br, bm, ml, mm, mr). See also gap_x and gap_y.
192 append_file
195 Append the file given as argument.
196 background
199 Boolean value, if true, Conky will be forked to background when
200 started.
201 border_inner_margin
204 Inner border margin in pixels (the margin between the border and
205 text).
206 border_outer_margin
209 Outer border margin in pixels (the margin between the border and
210 the edge of the window).
211 border_width
214 Border width in pixels.
215 colorN Predefine a color for use inside conky.text segments. Substi‐
218 tute N by a digit between 0 and 9, inclusively. When specifying
219 the color value in hex, omit the leading hash (#).
220 console_graph_ticks
223 A comma-separated list of strings to use as the bars of a graph
224 output to console/shell. The first list item is used for the
225 minimum bar height and the last item is used for the maximum.
226 Example: " ,_,=,#".
227 cpu_avg_samples
230 The number of samples to average for CPU monitoring.
231 default_bar_height
234 Specify a default height for bars. If not specified, the default
235 value is 6.
236 default_bar_width
239 Specify a default width for bars. If not specified, the default
240 value is 0, which causes the bar to expand to fit the width of
241 your Conky window. If you set out_to_console = true, the text
242 version of the bar will actually have no width and you will need
243 to set a sensible default or set the height and width of each
244 bar individually.
245 default_color
248 Default color and border color
249 default_gauge_height
252 Specify a default height for gauges. If not specified, the de‐
253 fault value is 25.
254 default_gauge_width
257 Specify a default width for gauges. If not specified, the de‐
258 fault value is 40.
259 default_graph_height
262 Specify a default height for graphs. If not specified, the de‐
263 fault value is 25.
264 default_graph_width
267 Specify a default width for graphs. If not specified, the de‐
268 fault value is 0, which causes the graph to expand to fit the
269 width of your Conky window. If you set out_to_console = true,
270 the text version of the graph will actually have no width and
271 you will need to set a sensible default or set the height and
272 width of each graph individually.
273 default_outline_color
276 Default outline color
277 default_shade_color
280 Default shading color and border's shading color
281 disable_auto_reload
284 Enable to disable the inotify-based auto config reload feature.
285 diskio_avg_samples
288 The number of samples to average for disk I/O monitoring.
289 display
292 Specify an X display to connect to.
293 xinerama_head
296 Specify a Xinerama head.
297 double_buffer
300 Use the Xdbe extension? (eliminates flicker) It is highly recom‐
301 mended to use own window with this one so double buffer won't be
302 so big.
303 draw_borders
306 Draw borders around text?
307 draw_graph_borders
310 Draw borders around graphs?
311 draw_outline
314 Draw outlines?
315 draw_shades
318 Draw shades?
319 extra_newline
322 Put an extra newline at the end when writing to stdout, useful
323 for writing to awesome's wiboxes.
324 font Font name in X, xfontsel can be used to get a nice font
327 format_human_readable
330 If enabled, values which are in bytes will be printed in human
331 readable format (i.e., KiB, MiB, etc). If disabled, the number
332 of bytes is printed instead.
333 gap_x Gap, in pixels, between right or left border of screen, same as
336 passing -x at command line, e.g. gap_x 10. For other position
337 related stuff, see 'alignment'.
338 gap_y Gap, in pixels, between top or bottom border of screen, same as
341 passing -y at command line, e.g. gap_y 10. For other position
342 related stuff, see 'alignment'.
343 hddtemp_host
346 Hostname to connect to for hddtemp objects. Defaults to
347 "127.0.0.1".
348 hddtemp_port
351 Port to use for hddtemp connections. Defaults to 7634.
352 http_refresh
355 When this is set the page generated with out_to_http will auto‐
356 matically refresh each interval. Default value is no.
357 if_up_strictness
360 How strict should if_up be when testing an interface for being
361 up? The value is one of up, link or address, to check for the
362 interface being solely up, being up and having link or being up,
363 having link and an assigned IP address.
364 imap Default global IMAP server. Arguments are: "host user pass [-i
367 interval (in seconds)] [-f 'folder'] [-p port] [-e 'command']
368 [-r retries]". Default port is 143, default folder is 'INBOX',
369 default interval is 5 minutes, and default number of retries be‐
370 fore giving up is 5. If the password is supplied as '*', you
371 will be prompted to enter the password when Conky starts.
372 imlib_cache_flush_interval
375 Interval (in seconds) to flush Imlib2 cache.
376 imlib_cache_size
379 Imlib2 image cache size, in bytes. Defaults to 4MiB. Increase
380 this value if you use $image lots. Set to 0 to disable the image
381 cache.
382 lua_draw_hook_post function_name [function arguments]
385 This function, if defined, will be called by Conky through each
386 iteration after drawing to the window. Requires X support. Takes
387 any number of optional arguments. Use this hook for drawing
388 things on top of what Conky draws. Conky puts 'conky_' in front
389 of function_name to prevent accidental calls to the wrong func‐
390 tion unless you place 'conky_' in front of it yourself.
391 lua_draw_hook_pre function_name [function arguments]
394 This function, if defined, will be called by Conky through each
395 iteration before drawing to the window. Requires X support.
396 Takes any number of optional arguments. Use this hook for draw‐
397 ing things on top of what Conky draws. Conky puts 'conky_' in
398 front of function_name to prevent accidental calls to the wrong
399 function unless you place 'conky_' in front of it yourself.
400 lua_load
403 Loads the Lua scripts separated by spaces.
404 lua_shutdown_hook function_name [function arguments]
407 This function, if defined, will be called by Conky at shutdown
408 or when the configuration is reloaded. Use this hook to clean up
409 after yourself, such as freeing memory which has been allocated
410 by external libraries via Lua. Conky puts 'conky_' in front of
411 function_name to prevent accidental calls to the wrong function
412 unless you place 'conky_' in front of it yourself.
413 lua_startup_hook function_name [function arguments]
416 This function, if defined, will be called by Conky at startup or
417 when the configuration is reloaded. Use this hook to initialize
418 values, or for any run-once applications. Conky puts 'conky_' in
419 front of function_name to prevent accidental calls to the wrong
420 function unless you place 'conky_' in front of it yourself.
421 mail_spool
424 Mail spool for mail checking
425 max_port_monitor_connections
428 Allow each port monitor to track at most this many connections
429 (if 0 or not set, default is 256)
430 max_text_width width
433 When a line in the output contains 'width' chars and the end
434 isn't reached, the next char will start on a new line. If you
435 want to make sure that lines don't get broken, set 'width' to 0
436 max_user_text bytes
439 Maximum size of user text buffer, i.e. text inside conky.text
440 section in config file (default is 16384 bytes)
441 maximum_width pixels
444 Maximum width of window
445 minimum_height height
448 Minimum height of the window
449 minimum_width width
452 Minimum width of window
453 mpd_host
456 Host of MPD server
457 mpd_password
460 MPD server password
461 mpd_port
464 Port of MPD server
465 mysql_host
468 Host of MySQL server. Defaults to localhost
469 mysql_port
472 Port of MySQL server. Defaults to the default mysql port
473 mysql_user
476 MySQL user name to use when connecting to the server. Defaults
477 to your username
478 mysql_password
481 Password of the MySQL user. Place it between "-chars. When this
482 is not set there is no password used
483 mysql_db
486 MySQL database to use. Defaults to mysql
487 music_player_interval
490 Music player thread update interval (defaults to Conky's update
491 interval)
492 net_avg_samples
495 The number of samples to average for net data
496 no_buffers
499 Subtract (file system) buffers from used memory?
500 nvidia_display
503 The display that the nvidia variable will use (defaults to the
504 value of the display variable)
505 out_to_console
508 Print text to stdout.
509 out_to_http
512 Let conky act as a small http-server serving it's text.
513 out_to_ncurses
516 Print text in the console, but use ncurses so that conky can
517 print the text of a new update over the old text. (In the future
518 this will provide more useful things)
519 out_to_stderr
522 Print text to stderr.
523 out_to_x
526 When set to no, there will be no output in X (useful when you
527 also use things like out_to_console). If you set it to no, make
528 sure that it's placed before all other X-related setting (take
529 the first line of your configfile to be sure). Default value is
530 yes
531 override_utf8_locale
534 Force UTF8? requires XFT
535 overwrite_file
538 Overwrite the file given as argument.
539 own_window
542 Boolean, create own window to draw?
543 own_window_class
546 Manually set the WM_CLASS name. Defaults to "Conky".
547 own_window_colour colour
550 If own_window_transparent no, set a specified background colour
551 (defaults to black). Takes either a hex value (e.g. ffffff, note
552 the lack of '#') or a valid RGB name (see /usr/lib/X11/rgb.txt)
553 own_window_hints undecorated,below,above,sticky,skip_taskbar,skip_pager
556 If own_window is yes, you may use these window manager hints to
557 affect the way Conky displays. Notes: Use own_window_type desk‐
558 top as another way to implement many of these hints implicitly.
559 If you use own_window_type override, window manager hints have
560 no meaning and are ignored.
561 own_window_title
564 Manually set the window name. Defaults to "conky (<hostname>)".
565 own_window_argb_visual
568 Boolean, use ARGB visual? ARGB can be used for real transparen‐
569 cy, note that a composite manager is required for real trans‐
570 parency. This option will not work as desired (in most cases) in
571 conjunction with 'own_window_type override'.
572 own_window_argb_value
575 When ARGB visuals are enabled, this use this to modify the alpha
576 value used. Valid range is 0-255, where 0 is 0% opacity, and 255
577 is 100% opacity.
578 own_window_transparent
581 Boolean, set transparency? If ARGB visual is enabled, sets back‐
582 ground opacity to 0%.
583 own_window_type
586 if own_window is yes, you may specify type normal, desktop,
587 dock, panel or override (default: normal). Desktop windows are
588 special windows that have no window decorations; are always vis‐
589 ible on your desktop; do not appear in your pager or taskbar;
590 and are sticky across all workspaces. Panel windows reserve
591 space along a desktop edge, just like panels and taskbars, pre‐
592 venting maximized windows from overlapping them. The edge is
593 chosen based on the alignment option. Override windows are not
594 under the control of the window manager. Hints are ignored. This
595 type of window can be useful for certain situations.
596 pad_percents
599 Pad percentages to this many decimals (0 = no padding)
600 pop3 Default global POP3 server. Arguments are: "host user pass [-i
603 interval (in seconds)] [-p port] [-e 'command'] [-r retries]".
604 Default port is 110, default interval is 5 minutes, and default
605 number of retries before giving up is 5. If the password is sup‐
606 plied as '*', you will be prompted to enter the password when
607 Conky starts.
608 short_units
611 Shortens units to a single character (kiB->k, GiB->G, etc.). De‐
612 fault is off.
613 show_graph_range
616 Shows the time range covered by a graph.
617 show_graph_scale
620 Shows the maximum value in scaled graphs.
621 stippled_borders
624 Border stippling (dashing) in pixels
625 temperature_unit
628 Desired output unit of all objects displaying a temperature. Pa‐
629 rameters are either "fahrenheit" or "celsius". The default unit
630 is degree Celsius.
631 templateN
634 Define a template for later use inside conky.text segments. Sub‐
635 stitute N by a digit between 0 and 9, inclusively. The value of
636 the variable is being inserted into the stuff inside conky.text
637 at the corresponding position, but before some substitutions are
638 applied:
639 '\n' -> newline
641 '\\' -> backslash
642 '\ ' -> space
643 '\N' -> template argument N (starting from 1)
644 text_buffer_size bytes
647 Size of the standard text buffer (default is 256 bytes). This
648 buffer is used for intermediary text, such as individual lines,
649 output from $exec vars, and various other variables. Increasing
650 the size of this buffer can drastically reduce Conky's perfor‐
651 mance, but will allow for more text display per variable. The
652 size of this buffer cannot be smaller than the default value of
653 256 bytes.
654 times_in_seconds
657 If true, variables that output times output a number that repre‐
658 sents seconds. This doesn't affect $time, $tztime and $utime
659 top_cpu_separate
662 If true, cpu in top will show usage of one processor's power. If
663 false, cpu in top will show the usage of all processors' power
664 combined.
665 top_name_verbose
668 If true, top name shows the full command line of each process,
669 including arguments (whenever possible). Otherwise, only the
670 basename is displayed. Default value is false.
671 top_name_width
674 Width for $top name value (defaults to 15 characters).
675 total_run_times
678 Total number of times for Conky to update before quitting. Zero
679 makes Conky run forever
680 update_interval seconds
683 Update interval
684 update_interval_on_battery seconds
687 Update interval when running on batterypower
688 uppercase
691 Boolean value, if true, text is rendered in upper case
692 use_spacer
695 Adds spaces around certain objects to stop them from moving oth‐
696 er things around. Arguments are left, right, and none (default).
697 The old true/false values are deprecated and default to
698 right/none respectively. Note that this only helps if you are
699 using a mono font, such as Bitstream Vera Sans Mono.
700 use_xft
703 Use Xft (anti-aliased font and stuff)
704 xftalpha
707 Alpha of Xft font. Must be a value at or between 1 and 0.
708
711 Colours are parsed using XParsecolor(), there might be a list of them:
712 /usr/share/X11/rgb.txt. Colour can be also in #rrggbb format (hex).
713 Some objects may create threads, and sometimes these threads will not
715 be destroyed until Conky terminates. There is no way to destroy or
716 clean up threads while Conky is running. For example, if you use an MPD
717 variable, the MPD thread will keep running until Conky dies. Some
718 threaded objects will use one of the parameters as a 'key', so that you
719 only have 1 relevant thread running (for example, the $curl, $rss and
720 $weather objects launch one thread per URI).
721 acpiacadapter (adapter)
723 ACPI ac adapter state. On linux, the adapter option specifies
724 the subfolder of /sys/class/power_supply containing the state
725 information (tries "AC" and "ADP1" if there is no argument giv‐
726 en). Non-linux systems ignore it.
727 acpifan
730 ACPI fan state
731 acpitemp
734 ACPI temperature in C.
735 addr (interface)
738 IP address for an interface, or "No Address" if no address is
739 assigned.
740 addrs (interface)
743 IP addresses for an interface (if one - works like addr). Linux
744 only.
745 adt746xcpu
748 CPU temperature from therm_adt746x
749 adt746xfan
752 Fan speed from therm_adt746x
753 alignc (num)
756 Align text to centre
757 alignr (num)
760 Right-justify text, with space of N
761 apcupsd host port
764 Sets up the connection to apcupsd daemon. Prints nothing, de‐
765 faults to localhost:3551
766 apcupsd_cable
769 Prints the UPS connection type.
770 apcupsd_charge
773 Current battery capacity in percent.
774 apcupsd_lastxfer
777 Reason for last transfer from line to battery.
778 apcupsd_linev
781 Nominal input voltage.
782 apcupsd_load
785 Current load in percent.
786 apcupsd_loadbar
789 Bar showing current load.
790 apcupsd_loadgauge (height),(width)
793 Gauge that shows current load.
794 apcupsd_loadgraph (height),(width) (gradient colour 1) (gradient colour
797 2) (scale) (-t) (-l)
798 History graph of current load.
799 apcupsd_model
802 Prints the model of the UPS.
803 apcupsd_name
806 Prints the UPS user-defined name.
807 apcupsd_status
810 Prints current status (on-line, on-battery).
811 apcupsd_temp
814 Current internal temperature.
815 apcupsd_timeleft
818 Time left to run on battery.
819 apcupsd_upsmode
822 Prints the UPS mode (e.g. standalone).
823 apm_adapter
826 Display APM AC adapter status (FreeBSD, OpenBSD only)
827 apm_battery_life
830 Display APM battery life in percent (FreeBSD, OpenBSD only)
831 apm_battery_time
834 Display remaining APM battery life in hh:mm:ss or "unknown" if
835 AC adapterstatus is on-line or charging (FreeBSD, OpenBSD only)
836 audacious_bar (height),(width)
839 Progress bar
840 audacious_bitrate
843 Bitrate of current tune
844 audacious_channels
847 Number of audio channels of current tune
848 audacious_filename
851 Full path and filename of current tune
852 audacious_frequency
855 Sampling frequency of current tune
856 audacious_length
859 Total length of current tune as MM:SS
860 audacious_length_seconds
863 Total length of current tune in seconds
864 audacious_main_volume
867 The current volume fetched from Audacious
868 audacious_playlist_length
871 Number of tunes in playlist
872 audacious_playlist_position
875 Playlist position of current tune
876 audacious_position
879 Position of current tune (MM:SS)
880 audacious_position_seconds
883 Position of current tune in seconds
884 audacious_status
887 Player status (Playing/Paused/Stopped/Not running)
888 audacious_title (max length)
891 Title of current tune with optional maximum length specifier
892 battery (num)
895 Battery status and remaining percentage capacity of ACPI or APM
896 battery. ACPI battery number can be given as argument (default
897 is BAT0).
898 battery_bar (height),(width) (num)
901 Battery percentage remaining of ACPI battery in a bar. ACPI bat‐
902 tery number can be given as argument (default is BAT0, use all
903 to get the mean percentage remaining for all batteries).
904 battery_percent (num)
907 Battery percentage remaining for ACPI battery. ACPI battery
908 number can be given as argument (default is BAT0, use all to get
909 the mean percentage remaining for all batteries).
910 battery_short (num)
913 Battery status and remaining percentage capacity of ACPI or APM
914 battery. ACPI battery number can be given as argument (default
915 is BAT0). This mode display a short status, which means that C
916 is displayed instead of charging, D for discharging, F for full,
917 N for not present, E for empty and U for unknown.
918 battery_time (num)
921 Battery charge/discharge time remaining of ACPI battery. ACPI
922 battery number can be given as argument (default is BAT0).
923 blink text_and_other_conky_vars
926 Let 'text_and_other_conky_vars' blink on and off.
927 bmpx_album
930 Album in current BMPx track
931 bmpx_artist
934 Artist in current BMPx track
935 bmpx_bitrate
938 Bitrate of the current BMPx track
939 bmpx_title
942 Title of the current BMPx track
943 bmpx_track
946 Track number of the current BMPx track
947 bmpx_uri
950 URI of the current BMPx track
951 buffers
954 Amount of memory buffered
955 cached Amount of memory cached
958 cmdline_to_pid string
961 PID of the first process that has string in it's commandline
962 cmus_aaa
965 Print aaa status of cmus (all/artist/album).
966 cmus_album
969 Prints the album of the current cmus song.
970 cmus_artist
973 Prints the artist of the current cmus song.
974 cmus_curtime
977 Current time of the current cmus song.
978 cmus_file
981 Print the file name of the current cmus song
982 cmus_date
985 Print the date of the current cmus song
986 cmus_genre
989 Print the genre name of the current cmus song
990 cmus_percent
993 Percent of song's progress.
994 cmus_progress (height),(width)
997 cmus' progress bar.
998 cmus_random
1001 Random status of cmus (on/off).
1002 cmus_repeat
1005 Repeat status of cmus (song/all/off).
1006 cmus_state
1009 Current state of cmus (playing, paused, stopped etc).
1010 cmus_timeleft
1013 Time left of the current cmus song.
1014 cmus_title
1017 Prints the title of the current cmus song.
1018 cmus_totaltime
1021 Total length of the current cmus song.
1022 cmus_track
1025 Print track number of current cmus song.
1026 color (color)
1029 Change drawing color to 'color' which is a name of a color or a
1030 hexcode preceded with # (for example #0A1B2C ). If you use
1031 ncurses only the following colors are supported: red,green,yel‐
1032 low,blue,magenta,cyan,black,white.
1033 colorN Change drawing color to colorN configuration option, where N is
1036 a digit between 0 and 9, inclusively.
1037 combine var1 var2
1040 Places the lines of var2 to the right of the lines of var1 sepa‐
1041 rated by the chars that are put between var1 and var2. For exam‐
1042 ple: ${combine ${head /proc/cpuinfo 2} - ${head /proc/meminfo
1043 1}} gives as output "cpuinfo_line1 - meminfo_line1" on line 1
1044 and "cpuinfo_line2 -" on line 2. $combine vars can also be nest‐
1045 ed to place more vars next to each other.
1046 conky_build_arch
1049 CPU architecture Conky was built for
1050 conky_build_date
1053 Date Conky was built
1054 conky_version
1057 Conky version
1058 cpu (cpuN)
1061 CPU usage in percents. For SMP machines, the CPU number can be
1062 provided as an argument. ${cpu cpu0} is the total usage, and
1063 ${cpu cpuX} (X >= 1) are individual CPUs.
1064 cpubar (cpuN) (height),(width)
1067 Bar that shows CPU usage, height is bar's height in pixels. See
1068 $cpu for more info on SMP.
1069 cpugauge (cpuN) (height),(width)
1072 Elliptical gauge that shows CPU usage, height and width are
1073 gauge's vertical and horizontal axis respectively. See $cpu for
1074 more info on SMP.
1075 cpugraph (cpuN) (height),(width) (gradient colour 1) (gradient colour
1078 2) (scale) (-t) (-l)
1079 CPU usage graph, with optional colours in hex, minus the #. See
1080 $cpu for more info on SMP. Uses a logarithmic scale (to see
1081 small numbers) when you use the -l switch. Takes the switch '-t'
1082 to use a temperature gradient, which makes the gradient values
1083 change depending on the amplitude of a particular graph value
1084 (try it and see).
1085 curl url (interval_in_minutes)
1088 Download data from URI using Curl at the specified interval. The
1089 interval may be a positive floating point value (0 is allowed),
1090 otherwise defaults to 15 minutes. Most useful when used in con‐
1091 junction with Lua and the Lua API. This object is threaded, and
1092 once a thread is created it can't be explicitly destroyed. One
1093 thread will run for each URI specified. You can use any protocol
1094 that Curl supports.
1095 desktop
1098 Number of the desktop on which conky is running or the message
1099 "Not running in X" if this is the case.
1100 desktop_name
1103 Name of the desktop on which conky is running or the message
1104 "Not running in X" if this is the case.
1105 desktop_number
1108 Number of desktops or the message "Not running in X" if this is
1109 the case.
1110 disk_protect device
1113 Disk protection status, if supported (needs kernel-patch).
1114 Prints either "frozen" or "free " (note the padding).
1115 diskio (device)
1118 Displays current disk IO. Device is optional, and takes the form
1119 of sda for /dev/sda. A block device label can be specified with
1120 label:foo. Individual partitions are also allowed.
1121 diskio_read (device)
1124 Displays current disk IO for reads. Device as in diskio.
1125 diskio_write (device)
1128 Displays current disk IO for writes. Device as in diskio.
1129 diskiograph (device) (height),(width) (gradient colour 1) (gradient
1132 colour 2) (scale) (-t) (-l)
1133 Disk IO graph, colours defined in hex, minus the #. If scale is
1134 non-zero, it becomes the scale for the graph. Uses a logarithmic
1135 scale (to see small numbers) when you use -l switch. Takes the
1136 switch '-t' to use a temperature gradient, which makes the gra‐
1137 dient values change depending on the amplitude of a particular
1138 graph value (try it and see).
1139 diskiograph_read (device) (height),(width) (gradient colour 1) (gradi‐
1142 ent colour 2) (scale) (-t) (-l)
1143 Disk IO graph for reads, colours defined in hex, minus the #. If
1144 scale is non-zero, it becomes the scale for the graph. Device as
1145 in diskio. Uses a logarithmic scale (to see small numbers) when
1146 you use -l switch. Takes the switch '-t' to use a temperature
1147 gradient, which makes the gradient values change depending on
1148 the amplitude of a particular graph value (try it and see).
1149 diskiograph_write (device) (height),(width) (gradient colour 1) (gradi‐
1152 ent colour 2) (scale) (-t) (-l)
1153 Disk IO graph for writes, colours defined in hex, minus the #.
1154 If scale is non-zero, it becomes the scale for the graph. Device
1155 as in diskio. Uses a logarithmic scale (to see small numbers)
1156 when you use -l switch. Takes the switch '-t' to use a tempera‐
1157 ture gradient, which makes the gradient values change depending
1158 on the amplitude of a particular graph value (try it and see).
1159 distribution
1162 The name of the distribution. It could be that some of the
1163 untested distributions will show up wrong or as "unknown", if
1164 that's the case post a bug on sourceforge, make sure it contains
1165 the name of your distribution, the contents of /proc/version and
1166 if there is a file that only exists on your distribution, also
1167 add the path of that file in the bug. If there is no such file,
1168 please add another way which we can use to identify your distri‐
1169 bution.
1170 downspeed (net)
1173 Download speed in suitable IEC units
1174 downspeedf (net)
1177 Download speed in KiB with one decimal
1178 downspeedgraph (netdev) (height),(width) (gradient colour 1) (gradient
1181 colour 2) (scale) (-t) (-l)
1182 Download speed graph, colours defined in hex, minus the #. If
1183 scale is non-zero, it becomes the scale for the graph. Uses a
1184 logarithmic scale (to see small numbers) when you use -l switch.
1185 Takes the switch '-t' to use a temperature gradient, which makes
1186 the gradient values change depending on the amplitude of a par‐
1187 ticular graph value (try it and see).
1188 draft_mails (maildir) (interval)
1191 Number of mails marked as draft in the specified mailbox or mail
1192 spool if not. Only maildir type mailboxes are supported, mbox
1193 type will return -1.
1194 else Text to show if any of the above are not true
1197 endif Ends an $if block.
1200 entropy_avail
1203 Current entropy available for crypto freaks
1204 entropy_bar (height),(width)
1207 Normalized bar of available entropy for crypto freaks
1208 entropy_perc
1211 Percentage of entropy available in comparison to the poolsize
1212 entropy_poolsize
1215 Total size of system entropy pool for crypto freaks
1216 eval string
1219 Evaluates given string according to the rules of conky.text in‐
1220 terpretation, i.e. parsing any contained text object specifica‐
1221 tions into their output, any occuring '$$' into a single '$' and
1222 so on. The output is then being parsed again.
1223 eve api_keyID api_vCode character_id
1226 Fetches a character's currently training skill from the Eve On‐
1227 line API servers (http://www.eveonline.com/) and displays the
1228 skill along with the remaining training time. If the character
1229 is not actively training a skill then returns the empty string
1230 (for use with $if_empty).
1231 exec command
1234 Executes a shell command and displays the output in conky. Warn‐
1235 ing: this takes a lot more resources than other variables. I'd
1236 recommend coding wanted behaviour in C/C++ and posting a patch.
1237 execbar (height),(width) command
1240 Same as exec, except if the first value returned is a value be‐
1241 tween 0-100, it will use that number to draw a horizontal bar.
1242 The height and width parameters are optional, and default to the
1243 default_bar_height and default_bar_width config settings, re‐
1244 spectively.
1245 execgauge (height),(width) command
1248 Same as exec, except if the first value returned is a value be‐
1249 tween 0-100, it will use that number to draw a round gauge (much
1250 like a vehicle speedometer). The height and width parameters are
1251 optional, and default to the default_gauge_height and de‐
1252 fault_gauge_width config settings, respectively.
1253 execgraph command (height),(width) (gradient color 1) (gradient color
1256 2) (scale) (-t) (-l)
1257 Draws a horizontally scrolling graph with values from 0-100
1258 plotted on the vertical axis. All parameters following the com‐
1259 mand are optional. Gradient colors can be specified as hexadeci‐
1260 mal values with no 0x or # prefix. Use the -t switch to enable a
1261 temperature gradient, so that small values are "cold" with color
1262 1 and large values are "hot" with color 2. Without the -t
1263 switch, the colors produce a horizontal gradient spanning the
1264 width of the graph. The scale parameter defines the maximum val‐
1265 ue of the graph. Use the -l switch to enable a logarithmic
1266 scale, which helps to see small values. The default size for
1267 graphs can be controlled via the default_graph_height and de‐
1268 fault_graph_width config settings.
1269 If you need to execute a command with spaces, you have a couple
1271 options: 1) wrap your command in double-quotes, or 2) put your
1272 command into a separate file, such as ~/bin/myscript.sh, and use
1273 that as your execgraph command. Remember to make your script ex‐
1274 ecutable!
1275 In the following example, we set up execgraph to display seconds
1277 (0-59) on a graph that is 50px high and 200px wide, using a tem‐
1278 perature gradient with colors ranging from red for small values
1279 (FF0000) to yellow for large values (FFFF00). We set the scale
1280 to 60.
1281 ${execgraph ~/seconds.sh 50,200 FF0000 FFFF00 60 -t}
1283 execi interval command
1285 Same as exec, but with a specific interval in seconds. The in‐
1286 terval can't be less than the update_interval in your configura‐
1287 tion. See also $texeci.
1288 execibar interval (height),(width) command
1291 Same as execbar, but with an interval.
1292 execigauge interval (height),(width) command
1295 Same as execgauge, but with an interval.
1296 execigraph interval command (height),(width) (gradient color 1) (gradi‐
1299 ent color 2) (scale) (-t) (-l)
1300 Same as execgraph, but with an interval.
1301 execp command
1304 Executes a shell command and displays the output in conky. Warn‐
1305 ing: this takes a lot more resources than other variables. I'd
1306 recommend coding wanted behaviour in C/C++ and posting a patch.
1307 This differs from $exec in that it parses the output of the com‐
1308 mand, so you can insert things like ${color red}hi!${color} in
1309 your script and have it correctly parsed by Conky. Caveats:
1310 Conky parses and evaluates the output of $execp every time Conky
1311 loops, and then destroys all the objects. If you try to use any‐
1312 thing like $execi within an $execp statement, it will function‐
1313 ally run at the same interval that the $execp statement runs, as
1314 it is created and destroyed at every interval.
1315 execpi interval command
1318 Same as execp, but with an interval. Note that the output from
1319 the $execpi command is still parsed and evaluated at every in‐
1320 terval.
1321 flagged_mails (maildir) (interval)
1324 Number of mails marked as flagged in the specified mailbox or
1325 mail spool if not. Only maildir type mailboxes are supported,
1326 mbox type will return -1.
1327 font (font)
1330 Specify a different font. This new font will apply to the cur‐
1331 rent line and everything following. You can use a $font with no
1332 arguments to change back to the default font (much like with
1333 $color)
1334 format_time seconds format
1337 Format time given in seconds. This var only works when the
1338 times_in_seconds configuration setting is on. Format is a string
1339 that should start and end with a "-char. The "-chars are not
1340 part of the output, \w,\d,\h,\m,\s,\(,\) and \\ are replaced by
1341 weeks,days,hours,minutes,seconds,(,) and \. If you leave out a
1342 unit, it's value will be expressed in the highest unite lower
1343 then the one left out. Text between ()-chars will not be visible
1344 if a replaced unit in this text is 0. If seconds is a decimal
1345 number then you can see the numbers behind the point by using \S
1346 followed by a number that specifies the amount of digits behind
1347 the point that you want to see (maximum 9). You can also place
1348 a 'x' behind \S so you have all digits behind the point and no
1349 trailing zero's. (also maximum 9)
1350 forwarded_mails (maildir) (interval)
1353 Number of mails marked as forwarded in the specified mailbox or
1354 mail spool if not. Only maildir type mailboxes are supported,
1355 mbox type will return -1.
1356 freq (n)
1359 Returns CPU #n's frequency in MHz. CPUs are counted from 1. If
1360 omitted, the parameter defaults to 1.
1361 freq_g (n)
1364 Returns CPU #n's frequency in GHz. CPUs are counted from 1. If
1365 omitted, the parameter defaults to 1.
1366 fs_bar (height),(width) fs
1369 Bar that shows how much space is used on a file system. height
1370 is the height in pixels. fs is any file on that file system.
1371 fs_bar_free (height),(width) fs
1374 Bar that shows how much space is free on a file system. height
1375 is the height in pixels. fs is any file on that file system.
1376 fs_free (fs)
1379 Free space on a file system available for users.
1380 fs_free_perc (fs)
1383 Free percentage of space on a file system available for users.
1384 fs_size (fs)
1387 File system size.
1388 fs_type (fs)
1391 File system type.
1392 fs_used (fs)
1395 File system used space.
1396 fs_used_perc (fs)
1399 Percent of file system used space.
1400 goto x The next element will be printed at position 'x'.
1403 gw_iface
1406 Displays the default route's interface or "multiple"/"none" ac‐
1407 cordingly.
1408 gw_ip Displays the default gateway's IP or "multiple"/"none" accord‐
1411 ingly.
1412 hddtemp (dev)
1415 Displays temperature of a selected hard disk drive as reported
1416 by the hddtemp daemon. Use hddtemp_host and hddtemp_port to
1417 specify a host and port for all hddtemp objects. If no dev pa‐
1418 rameter is given, the first disk returned by the hddtemp daemon
1419 is used.
1420 head logfile lines (next_check)
1423 Displays first N lines of supplied text file. The file is
1424 checked every 'next_check' update. If next_check is not sup‐
1425 plied, Conky defaults to 2. Max of 30 lines can be displayed, or
1426 until the text buffer is filled.
1427 hr (height)
1430 Horizontal line, height is the height in pixels
1431 hwmon (dev) type n (factor offset)
1434 Hwmon sensor from sysfs (Linux 2.6). Parameter dev may be omit‐
1435 ted if you have only one hwmon device. Parameter type is either
1436 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp' meaning
1437 temperature. Parameter n is number of the sensor. See
1438 /sys/class/hwmon/ on your local computer. The optional arguments
1439 'factor' and 'offset' allow precalculation of the raw input,
1440 which is being modified as follows: 'input = input * factor +
1441 offset'. Note that they have to be given as decimal values (i.e.
1442 contain at least one decimal place).
1443 i2c (dev) type n (factor offset)
1446 I2C sensor from sysfs (Linux 2.6). Parameter dev may be omitted
1447 if you have only one I2C device. Parameter type is either 'in'
1448 or 'vol' meaning voltage; 'fan' meaning fan; 'temp' meaning tem‐
1449 perature. Parameter n is number of the sensor. See
1450 /sys/bus/i2c/devices/ on your local computer. The optional argu‐
1451 ments 'factor' and 'offset' allow precalculation of the raw in‐
1452 put, which is being modified as follows: 'input = input * factor
1453 + offset'. Note that they have to be given as decimal values
1454 (i.e. contain at least one decimal place).
1455 i8k_ac_status
1458 If running the i8k kernel driver for Inspiron laptops, displays
1459 whether ac power is on, as listed in /proc/i8k (translated to
1460 human-readable). Beware that this is by default not enabled by
1461 i8k itself.
1462 i8k_bios
1465 If running the i8k kernel driver for Inspiron laptops, displays
1466 the bios version as listed in /proc/i8k.
1467 i8k_buttons_status
1470 If running the i8k kernel driver for Inspiron laptops, displays
1471 the volume buttons status as listed in /proc/i8k.
1472 i8k_cpu_temp
1475 If running the i8k kernel driver for Inspiron laptops, displays
1476 the cpu temperature in Celsius, as reported by /proc/i8k.
1477 i8k_left_fan_rpm
1480 If running the i8k kernel driver for Inspiron laptops, displays
1481 the left fan's rate of rotation, in revolutions per minute as
1482 listed in /proc/i8k. Beware, some laptops i8k reports these fans
1483 in reverse order.
1484 i8k_left_fan_status
1487 If running the i8k kernel driver for Inspiron laptops, displays
1488 the left fan status as listed in /proc/i8k (translated to human-
1489 readable). Beware, some laptops i8k reports these fans in re‐
1490 verse order.
1491 i8k_right_fan_rpm
1494 If running the i8k kernel driver for Inspiron laptops, displays
1495 the right fan's rate of rotation, in revolutions per minute as
1496 listed in /proc/i8k. Beware, some laptops i8k reports these fans
1497 in reverse order.
1498 i8k_right_fan_status
1501 If running the i8k kernel driver for Inspiron laptops, displays
1502 the right fan status as listed in /proc/i8k (translated to hu‐
1503 man-readable). Beware, some laptops i8k reports these fans in
1504 reverse order.
1505 i8k_serial
1508 If running the i8k kernel driver for Inspiron laptops, displays
1509 your laptop serial number as listed in /proc/i8k.
1510 i8k_version
1513 If running the i8k kernel driver for Inspiron laptops, displays
1514 the version formatting of /proc/i8k.
1515 ibm_brightness
1518 If running the IBM ACPI, displays the brigtness of the laptops's
1519 LCD (0-7).
1520 ibm_fan
1523 If running the IBM ACPI, displays the fan speed.
1524 ibm_temps N
1527 If running the IBM ACPI, displays the temperatures from the IBM
1528 temperature sensors (N=0..7) Sensor 0 is on the CPU, 3 is on the
1529 GPU.
1530 ibm_thinklight
1533 If running the IBM ACPI, displays the status of your Think‐
1534 Light™. Value is either 'on', 'off' or 'unknown'.
1535 ibm_volume
1538 If running the IBM ACPI, displays the "master" volume, con‐
1539 trolled by the volume keys (0-14).
1540 ical number file
1543 Shows title of event number 'number' in the ical (RFC 5545) file
1544 'file'. The events are first ordered by starting time, events
1545 that started in the past are ignored. The events that are shown
1546 are the VEVENTS, the title that is shown is the SUMMARY and the
1547 starting time used for sorting is DTSTART .
1548 irc server(:port) #channel (max_msg_lines)
1551 Shows everything that's being told in #channel on IRCserver
1552 'server'. TCP-port 6667 is used for the connection unless 'port'
1553 is specified. Shows everything since the last time or the last
1554 'max_msg_lines' entries if specified.
1555 iconv_start codeset_from codeset_to
1558 Convert text from one codeset to another using GNU iconv. Needs
1559 to be stopped with iconv_stop.
1560 iconv_stop
1563 Stop iconv codeset conversion.
1564 if_empty (var)
1567 if conky variable VAR is empty, display everything between
1568 $if_empty and the matching $endif
1569 if_existing file (string)
1572 if FILE exists, display everything between if_existing and the
1573 matching $endif. The optional second parameter checks for FILE
1574 containing the specified string and prints everything between
1575 $if_existing and the matching $endif.
1576 if_gw if there is at least one default gateway, display everything be‐
1579 tween $if_gw and the matching $endif
1580 if_match expression
1583 Evaluates the given boolean expression, printing everything be‐
1584 tween $if_match and the matching $endif depending on whether the
1585 evaluation returns true or not. Valid expressions consist of a
1586 left side, an operator and a right side. Left and right sides
1587 are being parsed for contained text objects before evaluation.
1588 Recognised left and right side types are:
1589 doubleArgument consists of only digits and a single dot.
1591 longArgument consists of only digits.
1592 stringArgument is enclosed in quotation marks (")
1593 Valid operands are: '>', '<', '>=', '<=', '==', '!='.
1595 if_mixer_mute (mixer)
1598 If mixer exists, display everything between $if_mixer_mute and
1599 the matching $endif. If no mixer is specified, "Vol" is used.
1600 if_mounted (mountpoint)
1603 if MOUNTPOINT is mounted, display everything between $if_mounted
1604 and the matching $endif
1605 if_mpd_playing
1608 if mpd is playing or paused, display everything between
1609 $if_mpd_playing and the matching $endif
1610 if_pa_sink_muted
1613 If Pulseaudio's default sink is muted, display everything be‐
1614 tween $if_pa_sink_muted and the corresponding $else or $endif.
1615 if_running (process)
1618 If PROCESS is running, display everything between $if_running
1619 and the corresponding $else or $endif. Note that PROCESS may be
1620 either a full command line with arguments (without the directory
1621 prefix), or simply the name of an executable. For example, ei‐
1622 ther of the following will be true if there is a running process
1623 with the command line /usr/bin/conky -u 5:
1624 ${if_running conky -u 5} or ${if_running conky}
1626 It is important not to include trailing spaces. For example,
1628 ${if_running conky } will be false.
1629 if_smapi_bat_installed (INDEX)
1632 when using smapi, if the battery with index INDEX is installed,
1633 display everything between $if_smapi_bat_installed and the
1634 matching $endif
1635 if_up (interface)
1638 if INTERFACE exists and is up, display everything between $if_up
1639 and the matching $endif
1640 if_updatenr (updatenr)
1643 If it's the UPDATENR-th time that conky updates, display every‐
1644 thing between $if_updatenr and the matching $endif. The counter
1645 resets when the highest UPDATENR is reached. Example : "{$if_up‐
1646 datenr 1}foo$endif{$if_updatenr 2}bar$endif{$if_updatenr 4}$en‐
1647 dif" shows foo 25% of the time followed by bar 25% of the time
1648 followed by nothing the other half of the time.
1649 if_xmms2_connected
1652 Display everything between $if_xmms2_connected and the matching
1653 $endif if xmms2 is running.
1654 image <path to image> (-p x,y) (-s WxH) (-n) (-f interval)
1657 Renders an image from the path specified using Imlib2. Takes 4
1658 optional arguments: a position, a size, a no-cache switch, and a
1659 cache flush interval. Changing the x,y position will move the
1660 position of the image, and changing the WxH will scale the im‐
1661 age. If you specify the no-cache flag (-n), the image will not
1662 be cached. Alternately, you can specify the -f int switch to
1663 specify a cache flush interval for a particular image. Example:
1664 ${image /home/brenden/cheeseburger.jpg -p 20,20 -s 200x200} will
1665 render 'cheeseburger.jpg' at (20,20) scaled to 200x200 pixels.
1666 Conky does not make any attempt to adjust the position (or any
1667 other formatting) of images, they are just rendered as per the
1668 arguments passed. The only reason $image is part of the
1669 conky.text section, is to allow for runtime modifications,
1670 through $execp $lua_parse, or some other method.
1671 imap_messages (args)
1674 Displays the number of messages in your global IMAP inbox by de‐
1675 fault. You can define individual IMAP inboxes separately by
1676 passing arguments to this object. Arguments are: "host user
1677 pass [-i interval (in seconds)] [-f 'folder'] [-p port] [-e
1678 'command'] [-r retries]". Default port is 143, default folder is
1679 'INBOX', default interval is 5 minutes, and default number of
1680 retries before giving up is 5. If the password is supplied as
1681 '*', you will be prompted to enter the password when Conky
1682 starts.
1683 imap_unseen (args)
1686 Displays the number of unseen messages in your global IMAP inbox
1687 by default. You can define individual IMAP inboxes separately by
1688 passing arguments to this object. Arguments are: "host user pass
1689 [-i interval (in seconds)] [-f 'folder'] [-p port] [-e 'com‐
1690 mand'] [-r retries]". Default port is 143, default folder is
1691 'INBOX', default interval is 5 minutes, and default number of
1692 retries before giving up is 5. If the password is supplied as
1693 '*', you will be prompted to enter the password when Conky
1694 starts.
1695 ioscheduler disk
1698 Prints the current ioscheduler used for the given disk name
1699 (i.e. e.g. "hda" or "sdb")
1700 journal lines (type)
1703 Displays last N lines of the systemd journal. The optional type
1704 can be 'user' or 'system' which will show only the user or sys‐
1705 tem journal respectively. By default, all journal lines visible
1706 to the user are shown. A maximum of 200 lines can be displayed,
1707 or until the text buffer is filled.
1708 kernel Kernel version
1711 version
1714 Git version numer (DragonFly only)
1715 laptop_mode
1718 The value of /proc/sys/vm/laptop_mode
1719 lines textfile
1722 Displays the number of lines in the given file
1723 loadavg (1|2|3)
1726 System load average, 1 is for past 1 minute, 2 for past 5 min‐
1727 utes and 3 for past 15 minutes. Without argument, prints all
1728 three values separated by whitespace.
1729 loadgraph (height),(width) (gradient colour 1) (gradient colour 2)
1732 (scale) (-t) (-l)
1733 Load1 average graph, similar to xload, with optional colours in
1734 hex, minus the #. Uses a logarithmic scale (to see small num‐
1735 bers) when you use the -l switch. Takes the switch '-t' to use
1736 a temperature gradient, which makes the gradient values change
1737 depending on the amplitude of a particular graph value (try it
1738 and see).
1739 lua function_name (function parameters)
1742 Executes a Lua function with given parameters, then prints the
1743 returned string. See also 'lua_load' on how to load scripts.
1744 Conky puts 'conky_' in front of function_name to prevent acci‐
1745 dental calls to the wrong function unless you put you place
1746 'conky_' in front of it yourself.
1747 lua_bar (height, width) function_name (function parameters)
1750 Executes a Lua function with given parameters and draws a bar.
1751 Expects result value to be an integer between 0 and 100. See al‐
1752 so 'lua_load' on how to load scripts. Conky puts 'conky_' in
1753 front of function_name to prevent accidental calls to the wrong
1754 function unless you put you place 'conky_' in front of it your‐
1755 self.
1756 lua_gauge (height, width) function_name (function parameters)
1759 Executes a Lua function with given parameters and draws a gauge.
1760 Expects result value to be an integer between 0 and 100. See al‐
1761 so 'lua_load' on how to load scripts. Conky puts 'conky_' in
1762 front of function_name to prevent accidental calls to the wrong
1763 function unless you put you place 'conky_' in front of it your‐
1764 self.
1765 lua_graph function_name (height),(width) (gradient colour 1) (gradient
1768 colour 2) (scale) (-t) (-l)
1769 Executes a Lua function with and draws a graph. Expects result
1770 value to be any number, and by default will scale to show the
1771 full range. See also 'lua_load' on how to load scripts. Takes
1772 the switch '-t' to use a temperature gradient, which makes the
1773 gradient values change depending on the amplitude of a particu‐
1774 lar graph value (try it and see). Conky puts 'conky_' in front
1775 of function_name to prevent accidental calls to the wrong func‐
1776 tion unless you put you place 'conky_' in front of it yourself.
1777 lua_parse function_name (function parameters)
1780 Executes a Lua function with given parameters as per $lua, then
1781 parses and prints the result value as per the syntax for the
1782 conky.text section. See also 'lua_load' on how to load scripts.
1783 Conky puts 'conky_' in front of function_name to prevent acci‐
1784 dental calls to the wrong function unless you put you place
1785 'conky_' in front of it yourself.
1786 machine
1789 Machine, i686 for example
1790 mails (mailbox) (interval)
1793 Mail count in the specified mailbox or your mail spool if not.
1794 Both mbox and maildir type mailboxes are supported. You can use
1795 a program like fetchmail to get mails from some server using
1796 your favourite protocol. See also new_mails.
1797 mboxscan (-n number of messages to print) (-fw from width) (-sw subject
1800 width) mbox
1801 Print a summary of recent messages in an mbox format mailbox.
1802 mbox parameter is the filename of the mailbox (can be encapsu‐
1803 lated using '"', ie. ${mboxscan -n 10 "/home/brenden/some box"}
1804 mem Amount of memory in use
1807 memwithbuffers
1810 Amount of memory in use, including that used by system buffers
1811 and caches
1812 membar (height),(width)
1815 Bar that shows amount of memory in use
1816 memwithbuffersbar (height),(width)
1819 Bar that shows amount of memory in use (including memory used by
1820 system buffers and caches)
1821 memdirty
1824 Amount of "dirty" memory (linux only)
1825 memeasyfree
1828 Amount of free memory including the memory that is very easily
1829 freed (buffers/cache)
1830 memfree
1833 Amount of free memory
1834 memgauge (height),(width)
1837 Gauge that shows amount of memory in use (see cpugauge)
1838 memgraph (height),(width) (gradient colour 1) (gradient colour 2)
1841 (scale) (-t) (-l)
1842 Memory usage graph. Uses a logarithmic scale (to see small num‐
1843 bers) when you use the -l switch. Takes the switch '-t' to use a
1844 temperature gradient, which makes the gradient values change de‐
1845 pending on the amplitude of a particular graph value (try it and
1846 see).
1847 memmax Total amount of memory
1850 memperc
1853 Percentage of memory in use
1854 mixer (device)
1857 Prints the mixer value as reported by the OS. On Linux, this
1858 variable uses the OSS emulation, so you need the proper kernel
1859 module loaded. Default mixer is "Vol", but you can specify one
1860 of the available OSS controls: "Vol", "Bass", "Trebl", "Synth",
1861 "Pcm", "Spkr", "Line", "Mic", "CD", "Mix", "Pcm2 ", "Rec",
1862 "IGain", "OGain", "Line1", "Line2", "Line3", "Digital1", "Digi‐
1863 tal2", "Digital3", "PhoneIn", "PhoneOut", "Video", "Radio" and
1864 "Monitor".
1865 mixerbar (device)
1868 Displays mixer value in a bar as reported by the OS. See docs
1869 for $mixer for details on arguments.
1870 mixerl (device)
1873 Prints the left channel mixer value as reported by the OS. See
1874 docs for $mixer for details on arguments.
1875 mixerlbar (device)
1878 Displays the left channel mixer value in a bar as reported by
1879 the OS. See docs for $mixer for details on arguments.
1880 mixerr (device)
1883 Prints the right channel mixer value as reported by the OS. See
1884 docs for $mixer for details on arguments.
1885 mixerrbar (device)
1888 Displays the right channel mixer value in a bar as reported by
1889 the OS. See docs for $mixer for details on arguments.
1890 moc_album
1893 Album of the current MOC song
1894 moc_artist
1897 Artist of the current MOC song
1898 moc_bitrate
1901 Bitrate in the current MOC song
1902 moc_curtime
1905 Current time of the current MOC song
1906 moc_file
1909 File name of the current MOC song
1910 moc_rate
1913 Rate of the current MOC song
1914 moc_song
1917 The current song name being played in MOC.
1918 moc_state
1921 Current state of MOC; playing, stopped etc.
1922 moc_timeleft
1925 Time left in the current MOC song
1926 moc_title
1929 Title of the current MOC song
1930 moc_totaltime
1933 Total length of the current MOC song
1934 monitor
1937 Number of the monitor on which conky is running or the message
1938 "Not running in X" if this is the case.
1939 monitor_number
1942 Number of monitors or the message "Not running in X" if this is
1943 the case.
1944 mpd_album
1947 Album in current MPD song
1948 mpd_artist
1951 Artist in current MPD song must be enabled at compile
1952 mpd_albumartist
1955 Artist of the album of the current MPD song.
1956 mpd_bar (height),(width)
1959 Bar of mpd's progress
1960 mpd_bitrate
1963 Bitrate of current song
1964 mpd_date
1967 Date of current song
1968 mpd_elapsed
1971 Song's elapsed time
1972 mpd_file
1975 Prints the file name of the current MPD song
1976 mpd_length
1979 Song's length
1980 mpd_name
1983 Prints the MPD name field
1984 mpd_percent
1987 Percent of song's progress
1988 mpd_random
1991 Random status (On/Off)
1992 mpd_repeat
1995 Repeat status (On/Off)
1996 mpd_smart (max length)
1999 Prints the song name in either the form "artist - title" or file
2000 name, depending on whats available
2001 mpd_status
2004 Playing, stopped, et cetera.
2005 mpd_title (max length)
2008 Title of current MPD song
2009 mpd_track
2012 Prints the MPD track field
2013 mpd_vol
2016 MPD's volume
2017 mysql query
2020 Shows the first field of the first row of the result of the
2021 query.
2022 nameserver (index)
2025 Print a nameserver from /etc/resolv.conf. Index starts at and
2026 defaults to 0.
2027 new_mails (mailbox) (interval)
2030 Unread mail count in the specified mailbox or mail spool if not.
2031 Both mbox and maildir type mailboxes are supported.
2032 nodename
2035 Hostname
2036 nodename_short
2039 Short hostname (same as 'hostname -s' shell command).
2040 no_update text
2043 Shows text and parses the vars in it, but doesn't update them.
2044 Use this for things that do not change while conky is running,
2045 like $machine, $conky_version,... By not updating this you can
2046 save some resources.
2047 nvidia argument (GPU_ID)
2050 Nvidia graphics card information via the XNVCtrl library.
2051 GPU_ID: Optional parameter to choose the GPU to be used as
2053 0,1,2,3,.. Default parameter is 0
2054 Possible arguments: (Temperatures are printed as float, all oth‐
2056 er values as integer. Bracketed arguments are aliases)
2057 gputemp (temp) GPU temperature
2059 gputempthreshold (threshold) Temperature threshold where the GPU
2060 will reduce it's clock speed
2061 ambienttemp (ambient) Ambient temperature outside the graphics
2062 card
2063 gpufreqcur (gpufreq) Current GPU clock speed
2064 gpufreqmin Minimum GPU clock speed
2065 gpufreqmax Maximum GPU clock speed
2066 memfreqcur (memfreq) Current memory clock speed
2067 memfreqmin Minimum memory clock speed
2068 memfreqmax Maximum memory clock speed
2069 mtrfreqcur (mtrfreq) Current memory transfer rate clock speed
2070 mtrfreqmin Minimum memory transfer rate clock speed
2071 mtrfreqmax Maximum memory transfer rate clock speed
2072 perflevelcur (perflevel) Current performance level
2073 perflevelmin Lowest performance level
2074 perflevelmax Highest performance level
2075 perfmode Performance mode
2076 gpuutil GPU utilization %
2077 membwutil Memory bandwidth utilization %
2078 videoutil Video engine utilization %
2079 pcieutil PCIe bandwidth utilization %
2080 memused (mem) Amount of used memory
2081 memfree (memavail) Amount of free memory
2082 memmax (memtotal) Total amount of memory
2083 memutil (memperc) Memory utilization %
2084 fanspeed Fan speed
2085 fanlevel Fan level %
2086 imagequality Image quality
2087 modelname name of the GPU card
2088 nvidiabar (height),(width) argument (GPU_ID)
2090 Same as nvidia, except it draws its output in a horizontal bar.
2091 The height and width parameters are optional, and default to the
2092 default_bar_height and default_bar_width config settings, re‐
2093 spectively.
2094 GPU_ID: Optional parameter to choose the GPU to be used as
2096 0,1,2,3,.. Default parameter is 0
2097 Note the following arguments are incompatible: gputempthreshold
2099 (threshold)
2100 gpufreqmin
2101 gpufreqmax
2102 memfreqmin
2103 memfreqmax
2104 mtrfreqmin
2105 mtrfreqmax
2106 perflevelmin
2107 perflevelmax
2108 perfmode
2109 memtotal (memmax)
2110 fanspeed
2111 nvidiagauge (height),(width) argument (GPU_ID)
2113 Same as nvidiabar, except a round gauge (much like a vehicle
2114 speedometer). The height and width parameters are optional, and
2115 default to the default_gauge_height and default_gauge_width con‐
2116 fig settings, respectively.
2117 GPU_ID: Optional parameter to choose the GPU to be used as
2119 0,1,2,3,.. Default parameter is 0
2120 For possible arguments see nvidia and nvidiabar.
2122 nvidiagraph argument (height),(width) (gradient color 1) (gradient col‐
2124 or 2) (scale) (-t) (-l) GPU_ID
2125 Same as nvidiabar, except a horizontally scrolling graph with
2126 values from 0-100 plotted on the vertical axis. The height and
2127 width parameters are optional, and default to the de‐
2128 fault_graph_height and default_graph_width config settings, re‐
2129 spectively.
2130 GPU_ID: NOT optional. This parameter allows to choose the GPU to
2132 be used as 0,1,2,3,..
2133 For possible arguments see nvidia and nvidiabar. To learn more
2135 about the -t -l and gradient color options, see execgraph.
2136 offset (pixels)
2138 Move text over by N pixels. See also $voffset.
2139 outlinecolor (color)
2142 Change outline color
2143 pa_sink_volume
2146 Pulseaudio's default sink volume percentage.
2147 pa_sink_volumebar
2150 Pulseaudio's default sink volume bar.
2151 pa_sink_description
2154 Pulseaudio's default sink description.
2155 pa_sink_active_port_name
2158 Pulseaudio's default sink active port name.
2159 pa_sink_active_port_description
2162 Pulseaudio's default sink active port description.
2163 pa_card_name
2166 Pulseaudio's default card name.
2167 pa_card_active_profile
2170 Pulseaudio's default card active profile.
2171 pb_battery item
2174 If running on Apple powerbook/ibook, display information on bat‐
2175 tery status. The item parameter specifies, what information to
2176 display. Exactly one item must be specified. Valid items are:
2177 status Display if battery is fully charged, charging, discharg‐
2179 ing or absent (running on AC)
2180 percent Display charge of battery in percent, if charging or
2181 discharging. Nothing will be displayed, if battery is fully
2182 charged or absent.
2183 time Display the time remaining until the battery will be fully
2184 charged or discharged at current rate. Nothing is displayed, if
2185 battery is absent or if it's present but fully charged and not
2186 discharging.
2187 pid_chroot pid
2190 Directory used as rootdirectory by the process (this will be "/"
2191 unless the process did a chroot syscall)
2192 pid_cmdline pid
2195 Command line this process was invoked with
2196 pid_cwd pid
2199 Current working directory of the process
2200 pid_environ pid varname
2203 Contents of a environment-var of the process
2204 pid_environ_list pid
2207 List of environment-vars that the process can see
2208 pid_exe pid
2211 Path to executed command that started the process
2212 pid_nice pid
2215 The nice value of the process
2216 pid_openfiles pid
2219 List of files that the process has open
2220 pid_parent pid
2223 The pid of the parent of the process
2224 pid_priority pid
2227 The priority of the process (see 'priority' in "man 5 proc")
2228 pid_read pid
2231 Total number of bytes read by the process
2232 pid_state pid
2235 State of the process
2236 pid_state_short pid
2239 One of the chars in "RSDZTW" representing the state of the
2240 process where R is running, S is sleeping in an interruptible
2241 wait, D is waiting in uninterruptible disk sleep, Z is zombie, T
2242 is traced or stopped (on a signal), and W is paging
2243 pid_stderr pid
2246 Filedescriptor binded to the STDERR of the process
2247 pid_stdin pid
2250 Filedescriptor binded to the STDIN of the process
2251 pid_stdout pid
2254 Filedescriptor binded to the STDOUT of the process
2255 pid_threads pid
2258 Number of threads in process containing this thread
2259 pid_thread_list pid
2262 List with pid's from threads from this process
2263 pid_time_kernelmode pid
2266 Amount of time that the process has been scheduled in kernel
2267 mode in seconds
2268 pid_time_usermode pid
2271 Amount of time that the process has been scheduled in user mode
2272 in seconds
2273 pid_time pid
2276 Sum of $pid_time_kernelmode and $pid_time_usermode
2277 pid_uid pid
2280 The real uid of the process
2281 pid_euid pid
2284 The effective uid of the process
2285 pid_suid pid
2288 The saved set uid of the process
2289 pid_fsuid pid
2292 The file system uid of the process
2293 pid_gid pid
2296 The real gid of the process
2297 pid_egid pid
2300 The effective gid of the process
2301 pid_sgid pid
2304 The saved set gid of the process
2305 pid_fsgid pid
2308 The file system gid of the process
2309 pid_vmpeak pid
2312 Peak virtual memory size of the process
2313 pid_vmsize pid
2316 Virtual memory size of the process
2317 pid_vmlck pid
2320 Locked memory size of the process
2321 pid_vmhwm pid
2324 Peak resident set size ("high water mark") of the process
2325 pid_vmrss pid
2328 Resident set size of the process
2329 pid_vmdata pid
2332 Data segment size of the process
2333 pid_vmstk pid
2336 Stack segment size of the process
2337 pid_vmexe pid
2340 Text segment size of the process
2341 pid_vmlib pid
2344 Shared library code size of the process
2345 pid_vmpte pid
2348 Page table entries size of the process
2349 pid_write pid
2352 Total number of bytes written by the process
2353 platform (dev) type n (factor offset)
2356 Platform sensor from sysfs (Linux 2.6). Parameter dev may be
2357 omitted if you have only one platform device. Platform type is
2358 either 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp'
2359 meaning temperature. Parameter n is number of the sensor. See
2360 /sys/bus/platform/devices/ on your local computer. The optional
2361 arguments 'factor' and 'offset' allow precalculation of the raw
2362 input, which is being modified as follows: 'input = input * fac‐
2363 tor + offset'. Note that they have to be given as decimal values
2364 (i.e. contain at least one decimal place).
2365 pop3_unseen (args)
2368 Displays the number of unseen messages in your global POP3 inbox
2369 by default. You can define individual POP3 inboxes separately by
2370 passing arguments to this object. Arguments are: "host user pass
2371 [-i interval (in seconds)] [-p port] [-e 'command'] [-r re‐
2372 tries]". Default port is 110, default interval is 5 minutes, and
2373 default number of retries before giving up is 5. If the password
2374 is supplied as '*', you will be prompted to enter the password
2375 when Conky starts.
2376 pop3_used (args)
2379 Displays the amount of space (in MiB, 2^20) used in your global
2380 POP3 inbox by default. You can define individual POP3 inboxes
2381 separately by passing arguments to this object. Arguments are:
2382 "host user pass [-i interval (in seconds)] [-p port] [-e 'com‐
2383 mand'] [-r retries]". Default port is 110, default interval is 5
2384 minutes, and default number of retries before giving up is 5. If
2385 the password is supplied as '*', you will be prompted to enter
2386 the password when Conky starts.
2387 processes
2390 Total processes (sleeping and running)
2391 read_tcp (host) port
2394 Connects to a tcp port on a host (default is localhost), reads
2395 every char available at the moment and shows them.
2396 read_udp (host) port
2399 Connects to a udp port on a host (default is localhost), reads
2400 every char available at the moment and shows them.
2401 replied_mails (maildir) (interval)
2404 Number of mails marked as replied in the specified mailbox or
2405 mail spool if not. Only maildir type mailboxes are supported,
2406 mbox type will return -1.
2407 rss uri interval_in_seconds action (num_par (spaces_in_front))
2410 Download and parse RSS feeds. The interval may be a (floating
2411 point) value greater than 0. Action may be one of the follow‐
2412 ing: feed_title, item_title (with num par), item_desc (with num
2413 par) and item_titles (when using this action and spaces_in_front
2414 is given conky places that many spaces in front of each item).
2415 This object is threaded, and once a thread is created it can't
2416 be explicitly destroyed. One thread will run for each URI speci‐
2417 fied. You can use any protocol that Curl supports.
2418 running_processes
2421 Running processes (not sleeping), requires Linux 2.6
2422 running_threads
2425 Number of running (runnable) threads. Linux only.
2426 scroll (direction) length (step) (interval) text
2429 Scroll 'text' by 'step' characters to the left or right (set
2430 'direction' to 'left' or 'right' or 'wait') showing 'length'
2431 number of characters at the same time. The text may also contain
2432 variables. 'step' is optional and defaults to 1 if not set. 'di‐
2433 rection' is optional and defaults to left if not set. When di‐
2434 rection is 'wait' then text will scroll left and wait for 'in‐
2435 terval' itertations at the beginning and end of the text. If a
2436 var creates output on multiple lines then the lines are placed
2437 behind each other separated with a '|'-sign. If you change the
2438 textcolor inside $scroll it will automatically have it's old
2439 value back at the end of $scroll. The end and the start of text
2440 will be separated by 'length' number of spaces unless direction
2441 is 'wait'.
2442 seen_mails (maildir) (interval)
2445 Number of mails marked as seen in the specified mailbox or mail
2446 spool if not. Only maildir type mailboxes are supported, mbox
2447 type will return -1.
2448 shadecolor (color)
2451 Change shading color
2452 smapi (ARGS)
2455 when using smapi, display contents of the /sys/devices/plat‐
2456 form/smapi directory. ARGS are either '(FILENAME)' or 'bat (IN‐
2457 DEX) (FILENAME)' to display the corresponding files' content.
2458 This is a very raw method of accessing the smapi values. When
2459 available, better use one of the smapi_* variables instead.
2460 smapi_bat_bar (INDEX),(height),(width)
2463 when using smapi, display the remaining capacity of the battery
2464 with index INDEX as a bar.
2465 smapi_bat_perc (INDEX)
2468 when using smapi, display the remaining capacity in percent of
2469 the battery with index INDEX. This is a separate variable be‐
2470 cause it supports the 'use_spacer' configuration option.
2471 smapi_bat_power INDEX
2474 when using smapi, display the current power of the battery with
2475 index INDEX in watt. This is a separate variable because the
2476 original read out value is being converted from mW. The sign of
2477 the output reflects charging (positive) or discharging (nega‐
2478 tive) state.
2479 smapi_bat_temp INDEX
2482 when using smapi, display the current temperature of the battery
2483 with index INDEX in degree Celsius. This is a separate variable
2484 because the original read out value is being converted from mil‐
2485 li degree Celsius.
2486 sony_fanspeed
2489 Displays the Sony VAIO fanspeed information if sony-laptop ker‐
2490 nel support is enabled. Linux only.
2491 stippled_hr (space)
2494 Stippled (dashed) horizontal line
2495 stock symbol data
2498 Displays the data of a stock symbol. The following data is sup‐
2499 ported: adv(Average Daily Volume), ask, asksize, bid, askrt(ask
2500 realtime), bidrt(bid realtime), bookvalue, bidsize, change, com‐
2501 mission, changert(change realtime), ahcrt(After Hours Change re‐
2502 altime), ds(dividend/share), ltd(Last Trade Date), tradedate,
2503 es(earnings/share), ei(error indication), epsecy(EPS Estimate
2504 Current Year), epseny(EPS Estimate Next Year), epsenq(EPS Esti‐
2505 mate Next Quarter), floatshares, dayslow, dayshigh, 52weeklow,
2506 52weekhigh, hgp(Holdings Gain Percent), ag(Annualized Gain),
2507 hg(Holdings Gain), hgprt(Holdings Gain Percent realtime),
2508 hgrt(Holdings Gain realtime), moreinfo, obrt(Order Book real‐
2509 time), mc(Market Capitalization), mcrt(Market Cap realtime),
2510 ebitda, c52wlow(Change From 52-week Low), pc52wlow(Percent
2511 Change From 52-week Low), cprt(change percent realtime),
2512 lts(Last Trade Size), c52whigh(Change from 52-week high),
2513 pc52whigh(percent change from 52-week high), ltp(last trade
2514 price), hl(high limit), ll(low limit), dr(day's range), dr‐
2515 rt(day's range realtime), 50ma(50-day Moving Average),
2516 200ma(200-day Moving Average), c200ma(Change From 200-day Moving
2517 Average), pc200ma(Percent Change From 200-day Moving Average),
2518 c50ma(Change From 50-day Moving Average), pc50ma(Percent Change
2519 From 50-day Moving Average), name, notes, open, pc(previous
2520 close), pricepaid, cip(change in percent), ps(price/sales),
2521 pb(price/book), edv(Ex-Dividend Date), per(P/E Ratio), dpd(Divi‐
2522 dend Pay Date), perrt(P/E Ratio realtime), pegr(PEG Ratio),
2523 pepsecy(Price/EPS Estimate Current Year), pepseny(Price/EPS Es‐
2524 timate Next Year), symbol, sharesowned, shortratio, ltt(Last
2525 Trade Time), tradelinks, tt(Ticker Trend), 1ytp(1 yr Target
2526 Price), volume, hv(Holdings Value), hvrt(Holdings Value real‐
2527 time), 52weekrange, dvc(Day's Value Change), dvcrt(Day's Value
2528 Change realtime), se(Stock Exchange), dy(Dividend Yield)
2529 swap Amount of swap in use
2532 swapbar (height),(width)
2535 Bar that shows amount of swap in use
2536 swapfree
2539 Amount of free swap
2540 swapmax
2543 Total amount of swap
2544 swapperc
2547 Percentage of swap in use
2548 sysname
2551 System name, Linux for example
2552 tab (width, (start))
2555 Puts a tab of the specified width, starting from column 'start'.
2556 The unit is pixels for both arguments.
2557 tail logfile lines (next_check)
2560 Displays last N lines of supplied text file. The file is checked
2561 every 'next_check' update. If next_check is not supplied, Conky
2562 defaults to 2. Max of 30 lines can be displayed, or until the
2563 text buffer is filled.
2564 tcp_ping host (port)
2567 Displays the number of microseconds it takes to get a reply on a
2568 ping to to tcp 'port' on 'host'. 'port' is optional and has 80
2569 as default. This works on both open and closed ports, just make
2570 sure that the port is not behind a firewall or you will get
2571 'down' as answer. It's best to test a closed port instead of an
2572 open port, you will get a quicker response.
2573 tcp_portmon port_begin port_end item (index)
2576 TCP port (both IPv6 and IPv4) monitor for specified local ports.
2577 Port numbers must be in the range 1 to 65535. Valid items are:
2578 count Total number of connections in the range
2580 rip Remote ip address
2581 rhost Remote host name
2582 rport Remote port number
2583 rservice Remote service name from /etc/services
2584 lip Local ip address
2585 lhost Local host name
2586 lport Local port number
2587 lservice Local service name from /etc/services
2588 The connection index provides you with access to each connection
2590 in the port monitor. The monitor will return information for in‐
2591 dex values from 0 to n-1 connections. Values higher than n-1 are
2592 simply ignored. For the "count" item, the connection index must
2593 be omitted. It is required for all other items.
2594 Examples:
2596 ${tcp_portmon 6881 6999 count} Displays the number of connec‐
2598 tions in the bittorrent port range
2599 ${tcp_portmon 22 22 rip 0} Displays the remote host ip of the
2600 first sshd connection
2601 ${tcp_portmon 22 22 rip 9} Displays the remote host ip of the
2602 tenth sshd connection
2603 ${tcp_portmon 1 1024 rhost 0} Displays the remote host name of
2604 the first connection on a privileged port
2605 ${tcp_portmon 1 1024 rport 4} Displays the remote host port of
2606 the fifth connection on a privileged port
2607 ${tcp_portmon 1 65535 lservice 14} Displays the local service
2608 name of the fifteenth connection in the range of all ports
2609 Note that port monitor variables which share the same port range
2611 actually refer to the same monitor, so many references to a sin‐
2612 gle port range for different items and different indexes all use
2613 the same monitor internally. In other words, the program avoids
2614 creating redundant monitors.
2615 templateN (arg1) (arg2) (arg3 ...)
2617 Evaluate the content of the templateN configuration variable
2618 (where N is a value between 0 and 9, inclusively), applying sub‐
2619 stitutions as described in the documentation of the correspond‐
2620 ing configuration variable. The number of arguments is optional,
2621 but must match the highest referred index in the template. You
2622 can use the same special sequences in each argument as the ones
2623 valid for a template definition, e.g. to allow an argument to
2624 contain a whitespace. Also simple nesting of templates is possi‐
2625 ble this way.
2626 Here are some examples of template definitions, note they are
2628 placed between [[ ... ]] instead of ' ... ':
2629 template0 = [[$\1\2]]
2631 template1 = [[\1: ${fs_used \2} / ${fs_size \2}]]
2632 template2 = [[\1 \2]]
2633 The following list shows sample usage of the templates defined
2635 above, with the equivalent syntax when not using any template at
2636 all:
2637 using template same without template
2639 ────────────────────────────────────────────────────────
2640 ${template0 node name} $nodename
2641 ${template1 root /} root: ${fs_free /} /
2642 ${fs_size /}
2643 ${template1 ${template2\ disk root: ${fs_free /} /
2644 disk\ root} /} ${fs_size /}
2645 texeci interval command
2647 Runs a command at an interval inside a thread and displays the
2648 output. Same as $execi, except the command is run inside a
2649 thread. Use this if you have a slow script to keep Conky updat‐
2650 ing. You should make the interval slightly longer than the time
2651 it takes your script to execute. For example, if you have a
2652 script that take 5 seconds to execute, you should make the in‐
2653 terval at least 6 seconds. See also $execi. This object will
2654 clean up the thread when it is destroyed, so it can safely be
2655 used in a nested fashion, though it may not produce the desired
2656 behaviour if used this way.
2657 texecpi interval command
2660 Same as execpi, except the command is run inside a thread.
2661 threads
2664 Total threads
2665 time (format)
2668 Local time, see man strftime to get more information about for‐
2669 mat
2670 to_bytes size
2673 If 'size' is a number followed by a size-unit (kilo‐
2674 byte,mb,GiB,...) then it converts the size to bytes and shows it
2675 without unit, otherwise it just shows 'size'.
2676 top type num
2679 This takes arguments in the form:top (name) (number) Basically,
2680 processes are ranked from highest to lowest in terms of cpu us‐
2681 age, which is what (num) represents. The types are: "name",
2682 "pid", "cpu", "mem", "mem_res", "mem_vsize", "time", "uid", "us‐
2683 er", "io_perc", "io_read" and "io_write". There can be a max of
2684 10 processes listed.
2685 top_io type num
2688 Same as top, except sorted by the amount of I/O the process has
2689 done during the update interval
2690 top_mem type num
2693 Same as top, except sorted by mem usage instead of cpu
2694 top_time type num
2697 Same as top, except sorted by total CPU time instead of current
2698 CPU usage
2699 totaldown (net)
2702 Total download, overflows at 4 GB on Linux with 32-bit arch and
2703 there doesn't seem to be a way to know how many times it has al‐
2704 ready done that before conky has started.
2705 totalup (net)
2708 Total upload, this one too, may overflow
2709 trashed_mails (maildir) (interval)
2712 Number of mails marked as trashed in the specified mailbox or
2713 mail spool if not. Only maildir type mailboxes are supported,
2714 mbox type will return -1.
2715 tztime (timezone (format))
2718 Local time for specified timezone, see man strftime to get more
2719 information about format. The timezone argument is specified in
2720 similar fashion as TZ environment variable. For hints, look in
2721 /usr/share/zoneinfo. e.g. US/Pacific, Europe/Zurich, etc.
2722 gid_name gid
2725 Name of group with this gid
2726 uid_name uid
2729 Username of user with this uid
2730 unflagged_mails (maildir) (interval)
2733 Number of mails not marked as flagged in the specified mailbox
2734 or mail spool if not. Only maildir type mailboxes are supported,
2735 mbox type will return -1.
2736 unforwarded_mails (maildir) (interval)
2739 Number of mails not marked as forwarded in the specified mailbox
2740 or mail spool if not. Only maildir type mailboxes are supported,
2741 mbox type will return -1.
2742 unreplied_mails (maildir) (interval)
2745 Number of mails not marked as replied in the specified mailbox
2746 or mail spool if not. Only maildir type mailboxes are supported,
2747 mbox type will return -1.
2748 unseen_mails (maildir) (interval)
2751 Number of new or unseen mails in the specified mailbox or mail
2752 spool if not. Only maildir type mailboxes are supported, mbox
2753 type will return -1.
2754 updates Number of updates
2757 for debugging
2758 upspeed (net)
2761 Upload speed in suitable IEC units
2762 upspeedf (net)
2765 Upload speed in KiB with one decimal
2766 upspeedgraph (netdev) (height),(width) (gradient colour 1) (gradient
2769 colour 2) (scale) (-t) (-l)
2770 Upload speed graph, colours defined in hex, minus the #. If
2771 scale is non-zero, it becomes the scale for the graph. Uses a
2772 logarithmic scale (to see small numbers) when you use the -l
2773 switch. Takes the switch '-t' to use a temperature gradient,
2774 which makes the gradient values change depending on the ampli‐
2775 tude of a particular graph value (try it and see).
2776 uptime Uptime
2779 uptime_short
2782 Uptime in a shorter format
2783 user_names
2786 Lists the names of the users logged in
2787 user_number
2790 Number of users logged in
2791 user_terms
2794 Lists the consoles in use
2795 user_times
2798 Lists how long users have been logged in for
2799 user_time console
2802 Lists how long the user for the given console has been logged in
2803 for
2804 utime (format)
2807 Display time in UTC (universal coordinate time).
2808 v6addrs (-n) (-s) (interface)
2811 IPv6 addresses for an interface, followed by netmask if -n is
2812 specified and scope with -s. Scopes are Global(G), Host-lo‐
2813 cal(H), Link-local(L), Site-local(S), Compat(C) and Unspeci‐
2814 fied(/). Linux only.
2815 voffset (pixels)
2818 Change vertical offset by N pixels. Negative values will cause
2819 text to overlap. See also $offset.
2820 voltage_mv (n)
2823 Returns CPU #n's voltage in mV. CPUs are counted from 1. If
2824 omitted, the parameter defaults to 1.
2825 voltage_v (n)
2828 Returns CPU #n's voltage in V. CPUs are counted from 1. If omit‐
2829 ted, the parameter defaults to 1.
2830 weather URI locID data_type (interval_in_minutes)
2833 Download, parse and display METAR data.
2834 For the 'URI', there are two possibilities:
2836 http://weather.noaa.gov/pub/data/observations/metar/stations/
2838 http://xoap.weather.com/weather/local/
2839 The first one is free to use but the second requires you to reg‐
2841 ister and obtain your partner ID and license key. These two must
2842 be written, separated by a space, into a file called .xoaprc
2843 which needs to be placed into your home directory.
2844 'locID' must be a valid location identifier for the required
2846 uri. For the NOAA site this must be a valid ICAO (see for in‐
2847 stance https://pilotweb.nas.faa.gov/qryhtml/icao/). For the
2848 weather.com site this must be a valid location ID (see for in‐
2849 stance http://aspnetresources.com/tools/locid.aspx).
2850 'data_type' must be one of the following:
2852 last_update The date and time stamp of the data. The result de‐
2854 pends on the URI used. For the NOAA site it is date (yyyy/mm/dd)
2855 and UTC time. For the weather.com one it is date ([m]m/[d]d/yy)
2856 and Local Time of the station.
2857 temperature
2858 Air temperature (you can use the 'temperature_unit' config set‐
2860 ting to change units)
2861 cloud_cover
2862 The highest cloud cover status
2864 pressure
2865 Air pressure in millibar
2867 wind_speed
2868 Wind speed in km/h
2870 wind_dir
2871 Wind direction
2873 wind_dir_DEG
2874 Compass wind direction
2876 humidity
2877 Relative humidity in %
2879 weather
2880 Any relevant weather event (rain, snow, etc.). This is not used
2882 if you are querying the weather.com site since this data is ag‐
2883 gregated into the cloud_cover one
2884 icon
2885 Weather icon (only for www.weather.com). Can be used together
2887 with the icon kit provided upon registering to their service.
2888 'delay_in_minutes' (optional, default 30) cannot be less than 30
2890 minutes.
2891 This object is threaded, and once a thread is created it can't
2893 be explicitly destroyed. One thread will run for each URI speci‐
2894 fied.
2895 Note that these variables are still EXPERIMENTAL and can be sub‐
2897 ject to many future changes.
2898 weather_forecast URI locID day data_type (interval_in_minutes)
2900 Download, parse and display weather forecast data for a given
2901 day (daytime only).
2902 For the 'URI', for the time being only http://xoap.weath‐
2904 er.com/weather/local/ is supported. See 'weather' above for de‐
2905 tails of usage
2906 'locID', see 'weather' above.
2908 'day' is a number from 0 (today) to 4 (3 days after tomorrow).
2910 'data_type' must be one of the following:
2912 day Day of the week
2914 date Date, in the form MMM DD (ie. Jul 14)
2915 low Minimun temperature (you can use the 'temperature_unit' con‐
2916 fig setting to change units)
2917 hi Maximum temperature (you can use the 'temperature_unit' con‐
2918 fig setting to change units)
2919 icon Weather icon. Can be used together with the icon kit pro‐
2920 vided upon registering to the weather.com service
2921 forecast Weather forecast (sunny, rainy, etc.)
2922 wind_speed Wind speed in km/h
2923 wind_dir Wind direction
2924 wind_dir_DEG Compass wind direction
2925 humidity Relative humidity in %
2926 precipitation Probability of having a precipitation (in %)
2927 'delay_in_minutes' (optional, default 210) cannot be lower than
2929 210 min.
2930 This object is threaded, and once a thread is created it can't
2932 be explicitly destroyed. One thread will run for each URI speci‐
2933 fied. You can use any protocol that Curl supports.
2934 Note that these variables are still EXPERIMENTAL and can be sub‐
2936 ject to many future changes.
2937 wireless_ap (net)
2939 Wireless access point MAC address (Linux only)
2940 wireless_bitrate (net)
2943 Wireless bitrate (ie 11 Mb/s) (Linux only)
2944 wireless_channel (net)
2947 WLAN channel on which device 'net' is listening (Linux only)
2948 wireless_essid (net)
2951 Wireless access point ESSID (Linux only)
2952 wireless_freq (net)
2955 Frequency on which device 'net' is listening (Linux only)
2956 wireless_link_bar (height),(width) (net)
2959 Wireless link quality bar (Linux only)
2960 wireless_link_qual (net)
2963 Wireless link quality (Linux only)
2964 wireless_link_qual_max (net)
2967 Wireless link quality maximum value (Linux only)
2968 wireless_link_qual_perc (net)
2971 Wireless link quality in percents (Linux only)
2972 wireless_mode (net)
2975 Wireless mode (Managed/Ad-Hoc/Master) (Linux only)
2976 words textfile
2979 Displays the number of words in the given file
2980 xmms2_album
2983 Album in current XMMS2 song
2984 xmms2_artist
2987 Artist in current XMMS2 song
2988 xmms2_bar (height),(width)
2991 Bar of XMMS2's progress
2992 xmms2_bitrate
2995 Bitrate of current song
2996 xmms2_comment
2999 Comment in current XMMS2 song
3000 xmms2_date
3003 Returns song's date.
3004 xmms2_duration
3007 Duration of current song
3008 xmms2_elapsed
3011 Song's elapsed time
3012 xmms2_genre
3015 Genre in current XMMS2 song
3016 xmms2_id
3019 XMMS2 id of current song
3020 xmms2_percent
3023 Percent of song's progress
3024 xmms2_playlist
3027 Returns the XMMS2 playlist.
3028 xmms2_size
3031 Size of current song
3032 xmms2_smart
3035 Prints the song name in either the form "artist - title" or file
3036 name, depending on whats available
3037 xmms2_status
3040 XMMS2 status (Playing, Paused, Stopped, or Disconnected)
3041 xmms2_timesplayed
3044 Number of times a song was played (presumably).
3045 xmms2_title
3048 Title in current XMMS2 song
3049 xmms2_tracknr
3052 Track number in current XMMS2 song
3053 xmms2_url
3056 Full path to current song
3057
3060 Conky features a Lua Programming API, and also ships with Lua bindings
3061 for some useful libraries. Note that the bindings require tolua++,
3062 which currently only compiles against Lua 5.1.
3063 To use Lua Conky, you first need to make sure you have a version of
3065 Conky with Lua support enabled (``conky -v'' will report this). Conky
3066 defines certain global functions and variables which can be accessed
3067 from Lua code running in Conky. Scripts must first be loaded using the
3068 lua_load configuration option. You then call functions in Lua via
3069 Conky's $lua, $lua_read, and Lua hooks.
3070 Be careful when creating threaded objects through the Lua API. You
3072 could wind up with a whole bunch of threads running if a thread is cre‐
3073 ated with each iteration.
3074 At this time, the Lua API should not be considered stable and may
3076 change drastically from one release to another as it matures.
3077 NOTE: In order to accommodate certain features in the cairo library's
3079 API, Conky will export a few additional functions for the creation of
3080 certain structures. These are documented below.
3081 conky_parse(string) function
3083 This function takes a string that is evaluated as per Conky's
3084 TEXT section, and then returns a string with the result.
3085 conky_set_update_interval(number) function
3087 Sets Conky's update interval (in seconds) to 'number'.
3088 conky_window table
3090 This table contains some information about Conky's window. The
3091 following table describes the values contained:
3092 drawable Window's drawable (Xlib Drawable), requires Lua extras
3094 enabled at compile time.
3095 visual Window's visual (Xlib Visual), requires Lua extras en‐
3096 abled at compile time.
3097 display Window's display (Xlib Display), requires Lua extras en‐
3098 abled at compile time.
3099 width Window width (in pixels).
3100 height Window height (in pixels).
3101 border_inner_margin Window's inner border margin (in pixels).
3102 border_outer_margin Window's outer border margin (in pixels).
3103 border_width Window's border width (in pixels).
3104 text_start_x The x component of the starting coordinate of text
3105 drawing.
3106 text_start_y The y component of the starting coordinate of text
3107 drawing.
3108 text_width The width of the text drawing region.
3109 text_height The height of the text drawing region.
3110 NOTE: This table is only defined when X support is enabled.
3112 conky_info table
3114 This table contains some information about Conky's internal da‐
3115 ta. The following table describes the values contained:
3116 update_interval Conky's update interval (in seconds).
3118 uptime System uptime, in seconds.
3119 conky_build_info string
3121 A string containing the build info for this particular instance
3122 of Conky, including the version, build date, and architecture.
3123 conky_build_date string
3125 A string containing the build date for this particular instance
3126 of Conky.
3127 conky_build_arch string
3129 A string containing the build architecture for this particular
3130 instance of Conky.
3131 conky_version string
3133 A string containing the version of the current instance of
3134 Conky.
3135 conky_config string
3137 A string containing the path of the current Conky configuration
3138 file.
3139 cairo_text_extents_t:create() function
3141 Call this function to return a new cairo_text_extents_t struc‐
3142 ture. A creation function for this structure is not provided by
3143 the cairo API. After calling this, you should use tolua.takeown‐
3144 ership() on the return value to ensure ownership is passed prop‐
3145 erly.
3146 cairo_font_extents_t:create() function
3148 Call this function to return a new cairo_font_extents_t struc‐
3149 ture. A creation function for this structure is not provided by
3150 the cairo API. After calling this, you should use tolua.takeown‐
3151 ership() on the return value to ensure ownership is passed prop‐
3152 erly.
3153 cairo_matrix_t:create() function
3155 Call this function to return a new cairo_matrix_t structure. A
3156 creation function for this structure is not provided by the
3157 cairo API. After calling this, you should use tolua.takeowner‐
3158 ship() on the return value to ensure ownership is passed proper‐
3159 ly.
3160
3162 conky -t '${time %D %H:%M}' -o -u 30
3163 Start Conky in its own window with date and clock as text and 30
3164 sec update interval.
3165 conky -a top_left -x 5 -y 500 -d
3167 Start Conky to background at coordinates (5, 500).
3168 conky -C > ~/.config/conky/conky.conf
3170 Do not start Conky, but have it output the builtin default con‐
3171 fig file to ~/.config/conky/conky.conf for later customising.
3172
3174 ${sysconfdir}/conky/conky.conf
3175 Default system-wide configuration file. The value of
3176 ${sysconfdir} depends on the compile-time options (most likely
3177 /etc).
3178 ~/.config/conky/conky.conf
3180 Default personal configuration file.
3181
3183 Drawing to root or some other desktop window directly doesn't work with
3184 all window managers. Especially doesn't work well with Gnome and it has
3185 been reported that it doesn't work with KDE either. Nautilus can be
3186 disabled from drawing to desktop with program gconf-editor. Uncheck
3187 show_desktop in /apps/nautilus/preferences/. There is -w switch in
3188 Conky to set some specific window id. You might find xwininfo -tree
3189 useful to find the window to draw to. You can also use -o argument
3190 which makes Conky to create its own window. If you do try running Conky
3191 in its own window, be sure to read up on the own_window_type settings
3192 and experiment.
3193
3195 〈http://conky.sourceforge.net/〉
3196 〈http://www.sourceforge.net/projects/conky〉
3198 〈http://wiki.conky.be〉
3200 #conky on irc.freenode.net
3202
3204 Copyright (c) 2005-2012 Brenden Matthews, Philip Kovacs, et. al. Any
3205 original torsmo code is licensed under the BSD license (see LICENSE.BSD
3206 for a copy). All code written since the fork of torsmo is licensed un‐
3207 der the GPL (see LICENSE.GPL for a copy), except where noted different‐
3208 ly (such as in portmon and audacious code which are LGPL, and prss
3209 which is an MIT-style license).
3210
3212 The Conky dev team (see AUTHORS for a full list of contributors).
3213 2012-05-03 conky(1)