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, Audacious), and much much more. Conky can display
26 this info either as text, or using simple progress bars and graph wid‐
27 gets, 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 app-
54 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.
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 ~/.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 | --display= DISPLAY
167 X11 display to use. Only available with build flag BUILD_X11 en‐
168 abled.
169 -y Y_COORDINATE
172 Y position.
173
176 Default configuration file location is ~/.config/conky/conky.conf or
177 ${sysconfdir}/conky/conky.conf. On most systems, sysconfdir is /etc,
178 and you can find the sample config file there in /etc/conky/conky.conf.
179 You might want to copy it to ~/.config/conky/conky.conf and then start
181 modifying it. Other configs can be found at https://github.com/brndnmt‐
182 thws/conky.
183 alignment
185 Aligned position on screen, may be top_left, top_right, top_mid‐
186 dle, bottom_left, bottom_right, bottom_middle, middle_left, mid‐
187 dle_middle, middle_right, or none (also can be abreviated as tl,
188 tr, tm, bl, br, bm, ml, mm, mr). See also gap_x and gap_y.
189 append_file
192 Append the file given as argument.
193 background
196 Boolean value, if true, Conky will be forked to background when
197 started.
198 forced_redraw
201 Boolean value, if true, Conky will redraw everything when you
202 switch the workspace. This may cause delays/flickering on some
203 WMs.
204 border_inner_margin
207 Inner border margin in pixels (the margin between the border and
208 text).
209 border_outer_margin
212 Outer border margin in pixels (the margin between the border and
213 the edge of the window).
214 border_width
217 Border width in pixels.
218 colorN Predefine a color for use inside conky.text segments. Substi‐
221 tute N by a digit between 0 and 9, inclusively. When specifying
222 the color value in hex, omit the leading hash (#).
223 console_bar_fill
226 A character to fill the console bars. (default: '#')
227 console_bar_unfill
230 A character to unfill the console bars. (default: '.')
231 console_graph_ticks
234 A comma-separated list of strings to use as the bars of a graph
235 output to console/shell. The first list item is used for the
236 minimum bar height and the last item is used for the maximum,
237 e.g. " ,_,=,#".
238 cpu_avg_samples
241 The number of samples to average for CPU monitoring.
242 default_bar_height
245 Specify a default height for bars. If not specified, the default
246 value is 6.
247 default_bar_width
250 Specify a default width for bars. If not specified, the default
251 value is 0, which causes the bar to expand to fit the width of
252 your Conky window. If you set out_to_console = true, the default
253 value will be 10 for the text version of the bar.
254 default_color
257 Default color and border color.
258 default_gauge_height
261 Specify a default height for gauges. If not specified, the de‐
262 fault value is 25.
263 default_gauge_width
266 Specify a default width for gauges. If not specified, the de‐
267 fault value is 40.
268 default_graph_height
271 Specify a default height for graphs. If not specified, the de‐
272 fault value is 25.
273 default_graph_width
276 Specify a default width for graphs. If not specified, the de‐
277 fault value is 0, which causes the graph to expand to fit the
278 width of your Conky window. If you set out_to_console = true,
279 the text version of the graph will actually have no width and
280 you will need to set a sensible default or set the height and
281 width of each graph individually.
282 default_outline_color
285 Default outline color.
286 default_shade_color
289 Default shading color and border's shading color.
290 disable_auto_reload
293 Enable to disable the inotify-based auto config reload feature.
294 diskio_avg_samples
297 The number of samples to average for disk I/O monitoring.
298 display
301 Specify an X display to connect to.
302 xinerama_head
305 Specify a Xinerama head.
306 double_buffer
309 Use the Xdbe extension? (eliminates flicker) It is highly recom‐
310 mended to use own window with this one so double buffer won't be
311 so big.
312 draw_blended
315 Boolean, blend when rendering drawn image? Some images blend in‐
316 correctly breaking alpha with ARBG visuals. This provides a pos‐
317 sible work around by disabling blending. Defaults to true.
318 draw_borders
321 Draw borders around text.
322 draw_graph_borders
325 Draw borders around graphs.
326 draw_outline
329 Draw outlines.
330 draw_shades
333 Draw shades.
334 extra_newline
337 Put an extra newline at the end when writing to stdout, useful
338 for writing to awesome's wiboxes.
339 font Font name in X, xfontsel can be used to get a nice font.
342 fontN Predefine a font to be used in conky.text segments. Substitute
345 N by a number between 0 and 9 inclusive. Use the same format as
346 a font variable.
347 format_human_readable
350 If enabled, values which are in bytes will be printed in human
351 readable format (i.e., KiB, MiB, etc). If disabled, the number
352 of bytes is printed instead.
353 gap_x Gap, in pixels, between right or left border of screen, same as
356 passing -x at command line, e.g. gap_x 10. For other position
357 related stuff, see 'alignment'.
358 gap_y Gap, in pixels, between top or bottom border of screen, same as
361 passing -y at command line, e.g. gap_y 10. For other position
362 related stuff, see 'alignment'.
363 github_token
366 Specify API token for GitHub notifications.
367 https://github.com/settings/tokens/new?scopes=notifications&de‐
369 scription=conky
370 hddtemp_host
373 Hostname to connect to for hddtemp objects. Defaults to
374 "127.0.0.1".
375 hddtemp_port
378 Port to use for hddtemp connections. Defaults to 7634.
379 http_refresh
382 When this is set the page generated with out_to_http will auto‐
383 matically refresh each interval. Default value is no.
384 if_up_strictness
387 How strict should if_up be when testing an interface for being
388 up? The value is one of up, link or address, to check for the
389 interface being solely up, being up and having link or being up,
390 having link and an assigned IP address.
391 imap Default global IMAP server. Arguments are: "host user pass [-i
394 interval (in seconds)] [-f 'folder'] [-p port] [-e 'command']
395 [-r retries]". Default port is 143, default folder is 'INBOX',
396 default interval is 5 minutes, and default number of retries be‐
397 fore giving up is 5. If the password is supplied as '*', you
398 will be prompted to enter the password when Conky starts.
399 imlib_cache_flush_interval
402 Interval (in seconds) to flush Imlib2 cache.
403 imlib_cache_size
406 Imlib2 image cache size, in bytes. Defaults to 4MiB. Increase
407 this value if you use $image lots. Set to 0 to disable the image
408 cache.
409 lua_draw_hook_post function_name [function arguments]
412 This function, if defined, will be called by Conky through each
413 iteration after drawing to the window. Requires X support. Takes
414 any number of optional arguments. Use this hook for drawing
415 things on top of what Conky draws. Conky puts 'conky_' in front
416 of function_name to prevent accidental calls to the wrong func‐
417 tion unless you place 'conky_' in front of it yourself.
418 lua_draw_hook_pre function_name [function arguments]
421 This function, if defined, will be called by Conky through each
422 iteration before drawing to the window. Requires X support.
423 Takes any number of optional arguments. Use this hook for draw‐
424 ing things on top of what Conky draws. Conky puts 'conky_' in
425 front of function_name to prevent accidental calls to the wrong
426 function unless you place 'conky_' in front of it yourself.
427 lua_load
430 Loads the Lua scripts separated by spaces.
431 lua_shutdown_hook function_name [function arguments]
434 This function, if defined, will be called by Conky at shutdown
435 or when the configuration is reloaded. Use this hook to clean up
436 after yourself, such as freeing memory which has been allocated
437 by external libraries via Lua. Conky puts 'conky_' in front of
438 function_name to prevent accidental calls to the wrong function
439 unless you place 'conky_' in front of it yourself.
440 lua_startup_hook function_name [function arguments]
443 This function, if defined, will be called by Conky at startup or
444 when the configuration is reloaded. Use this hook to initialize
445 values, or for any run-once applications. Conky puts 'conky_' in
446 front of function_name to prevent accidental calls to the wrong
447 function unless you place 'conky_' in front of it yourself.
448 mail_spool
451 Mail spool for mail checking.
452 max_port_monitor_connections
455 Allow each port monitor to track at most this many connections
456 (if 0 or not set, default is 256).
457 max_text_width width
460 When a line in the output contains 'width' chars and the end
461 isn't reached, the next char will start on a new line. If you
462 want to make sure that lines don't get broken, set 'width' to 0.
463 max_user_text bytes
466 Maximum size of user text buffer, i.e. text inside conky.text
467 section in config file (default is 16384 bytes).
468 maximum_width pixels
471 Maximum width of window.
472 minimum_height height
475 Minimum height of the window.
476 minimum_width width
479 Minimum width of window.
480 mpd_host
483 Host of MPD server.
484 mpd_password
487 MPD server password.
488 mpd_port
491 Port of MPD server.
492 mysql_host
495 Host of MySQL server. Defaults to localhost.
496 mysql_port
499 Port of MySQL server. Defaults to the default mysql port.
500 mysql_user
503 MySQL user name to use when connecting to the server. Defaults
504 to your username.
505 mysql_password
508 Password of the MySQL user. Place it between "-chars. When this
509 is not set there is no password used.
510 mysql_db
513 MySQL database to use. Defaults to mysql.
514 music_player_interval
517 Music player thread update interval (defaults to Conky's update
518 interval).
519 net_avg_samples
522 The number of samples to average for net data.
523 no_buffers
526 Subtract (file system) buffers from used memory.
527 nvidia_display
530 The display that the nvidia variable will use (defaults to the
531 value of the display variable).
532 out_to_console
535 Print text to stdout.
536 out_to_http
539 Let conky act as a small http-server serving its text.
540 out_to_ncurses
543 Print text in the console, but use ncurses so that conky can
544 print the text of a new update over the old text. (In the future
545 this will provide more useful things).
546 out_to_stderr
549 Print text to stderr.
550 out_to_x
553 When set to no, there will be no output in X (useful when you
554 also use things like out_to_console). If you set it to no, make
555 sure that it's placed before all other X-related setting (take
556 the first line of your configfile to be sure). Default value is
557 yes.
558 override_utf8_locale
561 Force UTF8. Requires XFT.
562 overwrite_file
565 Overwrite the file given as argument.
566 own_window
569 Boolean, create own window to draw.
570 own_window_class
573 Manually set the WM_CLASS name. Defaults to "Conky".
574 own_window_colour colour
577 If own_window_transparent no, set a specified background colour
578 (defaults to black). Takes either a hex value (e.g. '#ffffff'),
579 a shorthand hex value (e.g. '#fff'), or a valid RGB name (see
580 /usr/lib/X11/rgb.txt).
581 own_window_hints undecorated,below,above,sticky,skip_taskbar,skip_pager
584 If own_window is yes, you may use these window manager hints to
585 affect the way Conky displays. Notes: Use own_window_type desk‐
586 top as another way to implement many of these hints implicitly.
587 If you use own_window_type override, window manager hints have
588 no meaning and are ignored.
589 own_window_title
592 Manually set the window name. Defaults to "conky (<hostname>)".
593 own_window_argb_visual
596 Boolean, use ARGB visual? ARGB can be used for real transparen‐
597 cy, note that a composite manager is required for real trans‐
598 parency. This option will not work as desired (in most cases) in
599 conjunction with 'own_window_type override'.
600 own_window_argb_value
603 When ARGB visuals are enabled, this use this to modify the alpha
604 value used. Valid range is 0-255, where 0 is 0% opacity, and 255
605 is 100% opacity.
606 own_window_transparent
609 Boolean, set transparency? If ARGB visual is enabled, sets back‐
610 ground opacity to 0%.
611 own_window_type
614 if own_window is yes, you may specify type normal, desktop,
615 dock, panel or override (default: normal). Desktop windows are
616 special windows that have no window decorations; are always vis‐
617 ible on your desktop; do not appear in your pager or taskbar;
618 and are sticky across all workspaces. Panel windows reserve
619 space along a desktop edge, just like panels and taskbars, pre‐
620 venting maximized windows from overlapping them. The edge is
621 chosen based on the alignment option. Override windows are not
622 under the control of the window manager. Hints are ignored.
623 This type of window can be useful for certain situations.
624 pad_percents
627 Pad percentages to this many decimals (0 = no padding).
628 pop3 Default global POP3 server. Arguments are: "host user pass [-i
631 interval (in seconds)] [-p port] [-e 'command'] [-r retries]".
632 Default port is 110, default interval is 5 minutes, and default
633 number of retries before giving up is 5. If the password is sup‐
634 plied as '*', you will be prompted to enter the password when
635 Conky starts.
636 short_units
639 Shortens units to a single character (kiB->k, GiB->G, etc.). De‐
640 fault is off.
641 show_graph_range
644 Shows the time range covered by a graph.
645 show_graph_scale
648 Shows the maximum value in scaled graphs.
649 stippled_borders
652 Border stippling (dashing) in pixels.
653 temperature_unit
656 Desired output unit of all objects displaying a temperature.
657 Parameters are either "fahrenheit" or "celsius". The default
658 unit is degree Celsius.
659 templateN
662 Define a template for later use inside conky.text segments.
663 Substitute N by a digit between 0 and 9, inclusively. The value
664 of the variable is being inserted into the stuff inside
665 conky.text at the corresponding position, but before some sub‐
666 stitutions are applied:
667 '\n' -> newline
669 '\\' -> backslash
670 '\ ' -> space
671 '\N' -> template argument N (starting from 1)
672 text_buffer_size bytes
675 Size of the standard text buffer (default is 256 bytes). This
676 buffer is used for intermediary text, such as individual lines,
677 output from $exec vars, and various other variables. Increasing
678 the size of this buffer can drastically reduce Conky's perfor‐
679 mance, but will allow for more text display per variable. The
680 size of this buffer cannot be smaller than the default value of
681 256 bytes.
682 times_in_seconds
685 If true, variables that output times output a number that repre‐
686 sents seconds. This doesn't affect $time, $tztime and $utime.
687 top_cpu_separate
690 If true, cpu in top will show usage of one processor's power. If
691 false, cpu in top will show the usage of all processors' power
692 combined.
693 top_name_verbose
696 If true, top name shows the full command line of each process,
697 including arguments (whenever possible). Otherwise, only the
698 basename is displayed. Default value is false.
699 top_name_width
702 Width for $top name value (defaults to 15 characters).
703 total_run_times
706 Total number of times for Conky to update before quitting. Zero
707 makes Conky run forever.
708 update_interval seconds
711 Update interval.
712 update_interval_on_battery seconds
715 Update interval when running on battery power.
716 detect_battery
719 One or more batteries to check in order to use update_inter‐
720 val_on_battery (comma separated, BAT0 default).
721 uppercase
724 Boolean value, if true, text is rendered in upper case.
725 use_spacer
728 Adds spaces around certain objects to stop them from moving oth‐
729 er things around. Arguments are left, right, and none (default).
730 The old true/false values are deprecated and default to
731 right/none respectively. Note that this only helps if you are
732 using a mono font, such as Bitstream Vera Sans Mono.
733 use_xft
736 Use Xft (anti-aliased font and stuff).
737 xftalpha
740 Alpha of Xft font. Must be a value at or between 1 and 0.
741
744 Colours are parsed using XParsecolor(), there might be a list of them:
745 /usr/share/X11/rgb.txt. Colour can be also in #rrggbb format (hex).
746 Some objects may create threads, and sometimes these threads will not
748 be destroyed until Conky terminates. There is no way to destroy or
749 clean up threads while Conky is running. For example, if you use an MPD
750 variable, the MPD thread will keep running until Conky dies. Some
751 threaded objects will use one of the parameters as a 'key', so that you
752 only have 1 relevant thread running (for example, the $curl, $rss and
753 $weather objects launch one thread per URI).
754 acpiacadapter (adapter)
756 ACPI ac adapter state. On linux, the adapter option specifies
757 the subfolder of /sys/class/power_supply containing the state
758 information (tries "AC" and "ADP1" if there is no argument giv‐
759 en). Non-linux systems ignore it.
760 acpifan
763 ACPI fan state.
764 acpitemp
767 ACPI temperature in C.
768 addr (interface)
771 IP address for an interface, or "No Address" if no address is
772 assigned.
773 addrs (interface)
776 IP addresses for an interface (if one - works like addr). Linux
777 only.
778 adt746xcpu
781 CPU temperature from therm_adt746x.
782 adt746xfan
785 Fan speed from therm_adt746x.
786 alignc (num)
789 Align text to centre.
790 alignr (num)
793 Right-justify text, with space of N.
794 apcupsd host port
797 Sets up the connection to apcupsd daemon. Prints nothing, de‐
798 faults to localhost:3551.
799 apcupsd_cable
802 Prints the UPS connection type.
803 apcupsd_charge
806 Current battery capacity in percent.
807 apcupsd_lastxfer
810 Reason for last transfer from line to battery.
811 apcupsd_linev
814 Nominal input voltage.
815 apcupsd_load
818 Current load in percent.
819 apcupsd_loadbar
822 Bar showing current load.
823 apcupsd_loadgauge (height),(width)
826 Gauge that shows current load.
827 apcupsd_loadgraph (height),(width) (gradient colour 1) (gradient colour
830 2) (scale) (-t) (-l)
831 History graph of current load.
832 apcupsd_model
835 Prints the model of the UPS.
836 apcupsd_name
839 Prints the UPS user-defined name.
840 apcupsd_status
843 Prints current status (on-line, on-battery).
844 apcupsd_temp
847 Current internal temperature.
848 apcupsd_timeleft
851 Time left to run on battery.
852 apcupsd_upsmode
855 Prints the UPS mode (e.g. standalone).
856 apm_adapter
859 Display APM AC adapter status. FreeBSD, OpenBSD only.
860 apm_battery_life
863 Display APM battery life in percent. FreeBSD, OpenBSD only.
864 apm_battery_time
867 Display remaining APM battery life in hh:mm:ss or "unknown" if
868 AC adapterstatus is on-line or charging. FreeBSD, OpenBSD only.
869 audacious_bar (height),(width)
872 Progress bar.
873 audacious_bitrate
876 Bitrate of current tune.
877 audacious_channels
880 Number of audio channels of current tune.
881 audacious_filename
884 Full path and filename of current tune.
885 audacious_frequency
888 Sampling frequency of current tune.
889 audacious_length
892 Total length of current tune as MM:SS.
893 audacious_length_seconds
896 Total length of current tune in seconds.
897 audacious_main_volume
900 The current volume fetched from Audacious.
901 audacious_playlist_length
904 Number of tunes in playlist.
905 audacious_playlist_position
908 Playlist position of current tune.
909 audacious_position
912 Position of current tune (MM:SS).
913 audacious_position_seconds
916 Position of current tune in seconds.
917 audacious_status
920 Player status (Playing/Paused/Stopped/Not running).
921 audacious_title (max length)
924 Title of current tune with optional maximum length specifier.
925 battery (num)
928 Battery status and remaining percentage capacity of ACPI or APM
929 battery. ACPI battery number can be given as argument (default
930 is BAT0).
931 battery_bar (height),(width) (num)
934 Battery percentage remaining of ACPI battery in a bar. ACPI bat‐
935 tery number can be given as argument (default is BAT0, use all
936 to get the mean percentage remaining for all batteries).
937 battery_percent (num)
940 Battery percentage remaining for ACPI battery. ACPI battery num‐
941 ber can be given as argument (default is BAT0, use all to get
942 the mean percentage remaining for all batteries).
943 battery_short (num)
946 Battery status and remaining percentage capacity of ACPI or APM
947 battery. ACPI battery number can be given as argument (default
948 is BAT0). This mode display a short status, which means that C
949 is displayed instead of charging, D for discharging, F for full,
950 N for not present, E for empty and U for unknown.
951 battery_status (num)
954 Battery status for ACPI battery. ACPI battery number can be giv‐
955 en as argument (default is BAT0).
956 battery_time (num)
959 Battery charge/discharge time remaining of ACPI battery. ACPI
960 battery number can be given as argument (default is BAT0).
961 blink text_and_other_conky_vars
964 Let 'text_and_other_conky_vars' blink on and off.
965 buffers
968 Amount of memory buffered.
969 cached Amount of memory cached.
972 cat file
975 Reads a file and displays the contents in conky. This is useful
976 if you have an independent process generating output that you
977 want to include in conky.
978 catp file
981 Reads a file and displays the contents in conky. This is useful
982 if you have an independent process generating output that you
983 want to include in conky. This differs from $cat in that it
984 parses the contents of the file, so you can insert things like
985 ${color red}hi!${color} in your file and have it correctly
986 parsed by Conky.
987 cmdline_to_pid string
990 PID of the first process that has string in its commandline.
991 cmus_aaa
994 Print aaa status of cmus (all/artist/album).
995 cmus_album
998 Prints the album of the current cmus song.
999 cmus_artist
1002 Prints the artist of the current cmus song.
1003 cmus_curtime
1006 Current time of the current cmus song.
1007 cmus_file
1010 Print the file name of the current cmus song.
1011 cmus_date
1014 Print the date of the current cmus song.
1015 cmus_genre
1018 Print the genre name of the current cmus song.
1019 cmus_percent
1022 Percent of song's progress.
1023 cmus_progress (height),(width)
1026 cmus' progress bar.
1027 cmus_random
1030 Random status of cmus (on/off).
1031 cmus_repeat
1034 Repeat status of cmus (song/all/off).
1035 cmus_state
1038 Current state of cmus (playing, paused, stopped etc).
1039 cmus_timeleft
1042 Time left of the current cmus song.
1043 cmus_title
1046 Prints the title of the current cmus song.
1047 cmus_totaltime
1050 Total length of the current cmus song.
1051 cmus_track
1054 Print track number of current cmus song.
1055 color (color)
1058 Change drawing color to 'color' which is a name of a color or a
1059 hexcode preceded with #, e.g. #0A1B2C. If you use ncurses only
1060 the following colors are supported: red, green, yellow, blue,
1061 magenta, cyan, black, and white.
1062 colorN Change drawing color to colorN configuration option, where N is
1065 a digit between 0 and 9, inclusively.
1066 combine var1 var2
1069 Places the lines of var2 to the right of the lines of var1 sepa‐
1070 rated by the chars that are put between var1 and var2. For exam‐
1071 ple: ${combine ${head /proc/cpuinfo 2} - ${head /proc/meminfo
1072 1}} gives as output "cpuinfo_line1 - meminfo_line1" on line 1
1073 and "cpuinfo_line2 -" on line 2. $combine vars can also be nest‐
1074 ed to place more vars next to each other.
1075 conky_build_arch
1078 CPU architecture Conky was built for.
1079 conky_build_date
1082 Date Conky was built.
1083 conky_version
1086 Conky version.
1087 cpu (cpuN)
1090 CPU usage in percents. For SMP machines, the CPU number can be
1091 provided as an argument. ${cpu cpu0} is the total usage, and
1092 ${cpu cpuX} (X >= 1) are individual CPUs.
1093 cpubar (cpuN) (height),(width)
1096 Bar that shows CPU usage, height is bar's height in pixels. See
1097 $cpu for more info on SMP.
1098 cpugauge (cpuN) (height),(width)
1101 Elliptical gauge that shows CPU usage, height and width are
1102 gauge's vertical and horizontal axis respectively. See $cpu for
1103 more info on SMP.
1104 cpugraph (cpuN) (height),(width) (gradient colour 1) (gradient colour
1107 2) (scale) (-t) (-l)
1108 CPU usage graph, with optional colours in hex, minus the #. See
1109 $cpu for more info on SMP. Uses a logarithmic scale (to see
1110 small numbers) when you use the -l switch. Takes the switch '-t'
1111 to use a temperature gradient, which makes the gradient values
1112 change depending on the amplitude of a particular graph value
1113 (try it and see).
1114 curl url (interval_in_minutes)
1117 Download data from URI using Curl at the specified interval.
1118 The interval may be a positive floating point value (0 is al‐
1119 lowed), otherwise defaults to 15 minutes. Most useful when used
1120 in conjunction with Lua and the Lua API. This object is thread‐
1121 ed, and once a thread is created it can't be explicitly de‐
1122 stroyed. One thread will run for each URI specified. You can use
1123 any protocol that Curl supports.
1124 desktop
1127 Number of the desktop on which conky is running or the message
1128 "Not running in X" if this is the case.
1129 desktop_name
1132 Name of the desktop on which conky is running or the message
1133 "Not running in X" if this is the case.
1134 desktop_number
1137 Number of desktops or the message "Not running in X" if this is
1138 the case.
1139 disk_protect device
1142 Disk protection status, if supported (needs kernel-patch).
1143 Prints either "frozen" or "free " (note the padding).
1144 diskio (device)
1147 Displays current disk IO. Device is optional, and takes the form
1148 of sda for /dev/sda. A block device label can be specified with
1149 label:foo and a block device partuuid can be specified with par‐
1150 tuuid:40000000-01.
1151 diskio_read (device)
1154 Displays current disk IO for reads. Device as in diskio.
1155 diskio_write (device)
1158 Displays current disk IO for writes. Device as in diskio.
1159 diskiograph (device) (height),(width) (gradient colour 1) (gradient
1162 colour 2) (scale) (-t) (-l)
1163 Disk IO graph, colours defined in hex, minus the #. If scale is
1164 non-zero, it becomes the scale for the graph. Uses a logarithmic
1165 scale (to see small numbers) when you use -l switch. Takes the
1166 switch '-t' to use a temperature gradient, which makes the gra‐
1167 dient values change depending on the amplitude of a particular
1168 graph value (try it and see).
1169 diskiograph_read (device) (height),(width) (gradient colour 1) (gradi‐
1172 ent colour 2) (scale) (-t) (-l)
1173 Disk IO graph for reads, colours defined in hex, minus the #. If
1174 scale is non-zero, it becomes the scale for the graph. Device as
1175 in diskio. Uses a logarithmic scale (to see small numbers) when
1176 you use -l switch. Takes the switch '-t' to use a temperature
1177 gradient, which makes the gradient values change depending on
1178 the amplitude of a particular graph value (try it and see).
1179 diskiograph_write (device) (height),(width) (gradient colour 1) (gradi‐
1182 ent colour 2) (scale) (-t) (-l)
1183 Disk IO graph for writes, colours defined in hex, minus the #.
1184 If scale is non-zero, it becomes the scale for the graph. Device
1185 as in diskio. Uses a logarithmic scale (to see small numbers)
1186 when you use -l switch. Takes the switch '-t' to use a tempera‐
1187 ture gradient, which makes the gradient values change depending
1188 on the amplitude of a particular graph value (try it and see).
1189 distribution
1192 The name of the distribution. It could be that some of the
1193 untested distributions will show up wrong or as "unknown", if
1194 that's the case post a bug on sourceforge, make sure it contains
1195 the name of your distribution, the contents of /proc/version and
1196 if there is a file that only exists on your distribution, also
1197 add the path of that file in the bug. If there is no such file,
1198 please add another way which we can use to identify your distri‐
1199 bution.
1200 downspeed (net)
1203 Download speed in suitable IEC units.
1204 downspeedf (net)
1207 Download speed in KiB with one decimal.
1208 downspeedgraph (netdev) (height),(width) (gradient colour 1) (gradient
1211 colour 2) (scale) (-t) (-l)
1212 Download speed graph, colours defined in hex, minus the #. If
1213 scale is non-zero, it becomes the scale for the graph. Uses a
1214 logarithmic scale (to see small numbers) when you use -l switch.
1215 Takes the switch '-t' to use a temperature gradient, which makes
1216 the gradient values change depending on the amplitude of a par‐
1217 ticular graph value (try it and see).
1218 draft_mails (maildir) (interval)
1221 Number of mails marked as draft in the specified mailbox or mail
1222 spool if not. Only maildir type mailboxes are supported, mbox
1223 type will return -1.
1224 else Text to show if any of the above are not true.
1227 endif Ends an $if block.
1230 entropy_avail
1233 Current entropy available for crypto freaks.
1234 entropy_bar (height),(width)
1237 Normalized bar of available entropy for crypto freaks.
1238 entropy_perc
1241 Percentage of entropy available in comparison to the poolsize.
1242 entropy_poolsize
1245 Total size of system entropy pool for crypto freaks.
1246 eval string
1249 Evaluates given string according to the rules of conky.text in‐
1250 terpretation, i.e. parsing any contained text object specifica‐
1251 tions into their output, any occuring '$$' into a single '$' and
1252 so on. The output is then being parsed again.
1253 exec command
1256 Executes a shell command and displays the output in conky.
1257 Warning: this takes a lot more resources than other variables.
1258 I'd recommend coding wanted behaviour in C/C++ and posting a
1259 patch.
1260 execbar (height),(width) command
1263 Same as exec, except if the first value returned is a value be‐
1264 tween 0-100, it will use that number to draw a horizontal bar.
1265 The height and width parameters are optional, and default to the
1266 default_bar_height and default_bar_width config settings, re‐
1267 spectively.
1268 execgauge (height),(width) command
1271 Same as exec, except if the first value returned is a value be‐
1272 tween 0-100, it will use that number to draw a round gauge (much
1273 like a vehicle speedometer). The height and width parameters are
1274 optional, and default to the default_gauge_height and de‐
1275 fault_gauge_width config settings, respectively.
1276 execgraph command (height),(width) (gradient color 1) (gradient color
1279 2) (scale) (-t) (-l)
1280 Draws a horizontally scrolling graph with values from 0-100
1281 plotted on the vertical axis. All parameters following the com‐
1282 mand are optional. Gradient colors can be specified as hexadeci‐
1283 mal values with no 0x or # prefix. Use the -t switch to enable a
1284 temperature gradient, so that small values are "cold" with color
1285 1 and large values are "hot" with color 2. Without the -t
1286 switch, the colors produce a horizontal gradient spanning the
1287 width of the graph. The scale parameter defines the maximum val‐
1288 ue of the graph. Use the -l switch to enable a logarithmic
1289 scale, which helps to see small values. The default size for
1290 graphs can be controlled via the default_graph_height and de‐
1291 fault_graph_width config settings.
1292 If you need to execute a command with spaces, you have a couple
1294 options: 1) wrap your command in double-quotes, or 2) put your
1295 command into a separate file, such as ~/bin/myscript.sh, and use
1296 that as your execgraph command. Remember to make your script ex‐
1297 ecutable!
1298 In the following example, we set up execgraph to display seconds
1300 (0-59) on a graph that is 50px high and 200px wide, using a tem‐
1301 perature gradient with colors ranging from red for small values
1302 (FF0000) to yellow for large values (FFFF00). We set the scale
1303 to 60.
1304 ${execgraph ~/seconds.sh 50,200 FF0000 FFFF00 60 -t}
1306 execi interval command
1308 Same as exec, but with a specific interval in seconds. The in‐
1309 terval can't be less than the update_interval in your configura‐
1310 tion. See also $texeci.
1311 execibar interval (height),(width) command
1314 Same as execbar, but with an interval.
1315 execigauge interval (height),(width) command
1318 Same as execgauge, but with an interval.
1319 execigraph interval command (height),(width) (gradient color 1) (gradi‐
1322 ent color 2) (scale) (-t) (-l)
1323 Same as execgraph, but with an interval.
1324 execp command
1327 Executes a shell command and displays the output in conky.
1328 Warning: this takes a lot more resources than other variables.
1329 I'd recommend coding wanted behaviour in C/C++ and posting a
1330 patch. This differs from $exec in that it parses the output of
1331 the command, so you can insert things like ${color red}hi!${col‐
1332 or} in your script and have it correctly parsed by Conky.
1333 Caveats: Conky parses and evaluates the output of $execp every
1334 time Conky loops, and then destroys all the objects. If you try
1335 to use anything like $execi within an $execp statement, it will
1336 functionally run at the same interval that the $execp statement
1337 runs, as it is created and destroyed at every interval.
1338 execpi interval command
1341 Same as execp, but with an interval. Note that the output from
1342 the $execpi command is still parsed and evaluated at every in‐
1343 terval.
1344 flagged_mails (maildir) (interval)
1347 Number of mails marked as flagged in the specified mailbox or
1348 mail spool if not. Only maildir type mailboxes are supported,
1349 mbox type will return -1.
1350 font (font)
1353 Specify a different font. This new font will apply to the cur‐
1354 rent line and everything following. You can use a $font with no
1355 arguments to change back to the default font (much like with
1356 $color).
1357 fontN Change font to fontN configuration option, where N is a digit
1360 between 0 and 9, inclusively.
1361 format_time seconds format
1364 Format time given in seconds. This var only works when the
1365 times_in_seconds configuration setting is on. Format is a string
1366 that should start and end with a "-char. The "-chars are not
1367 part of the output, \w,\d,\h,\m,\s,\(,\) and \\ are replaced by
1368 weeks,days,hours,minutes,seconds,(,) and \. If you leave out a
1369 unit, it's value will be expressed in the highest unit lower
1370 than the one left out. Text between ()-chars will not be visible
1371 if a replaced unit in this text is 0. If seconds is a decimal
1372 number then you can see the numbers behind the point by using \S
1373 followed by a number that specifies the amount of digits behind
1374 the point that you want to see (maximum 9). You can also place a
1375 'x' behind \S so you have all digits behind the point and no
1376 trailing zero's. (also maximum 9).
1377 forwarded_mails (maildir) (interval)
1380 Number of mails marked as forwarded in the specified mailbox or
1381 mail spool if not. Only maildir type mailboxes are supported,
1382 mbox type will return -1.
1383 freq (n)
1386 Returns CPU #n's frequency in MHz. CPUs are counted from 1. If
1387 omitted, the parameter defaults to 1.
1388 freq_g (n)
1391 Returns CPU #n's frequency in GHz. CPUs are counted from 1. If
1392 omitted, the parameter defaults to 1.
1393 freq2 (n)
1396 Returns CPU #n's clock speed from assembly in MHz. CPUs are
1397 counted from 1. If omitted, the parameter defaults to 1.
1398 fs_bar (height),(width) fs
1401 Bar that shows how much space is used on a file system. height
1402 is the height in pixels. fs is any file on that file system.
1403 fs_bar_free (height),(width) fs
1406 Bar that shows how much space is free on a file system. height
1407 is the height in pixels. fs is any file on that file system.
1408 fs_free (fs)
1411 Free space on a file system available for users.
1412 fs_free_perc (fs)
1415 Free percentage of space on a file system available for users.
1416 fs_size (fs)
1419 File system size.
1420 fs_type (fs)
1423 File system type.
1424 fs_used (fs)
1427 File system used space.
1428 fs_used_perc (fs)
1431 Percent of file system used space.
1432 github_notifications
1435 Number of GitHub notifications.
1436 goto x The next element will be printed at position 'x'.
1439 gw_iface
1442 Displays the default route's interface or "multiple"/"none" ac‐
1443 cordingly.
1444 gw_ip Displays the default gateway's IP or "multiple"/"none" accord‐
1447 ingly.
1448 hddtemp (dev)
1451 Displays temperature of a selected hard disk drive as reported
1452 by the hddtemp daemon. Use hddtemp_host and hddtemp_port to
1453 specify a host and port for all hddtemp objects. If no dev pa‐
1454 rameter is given, the first disk returned by the hddtemp daemon
1455 is used.
1456 head logfile lines (next_check)
1459 Displays first N lines of supplied text file. The file is
1460 checked every 'next_check' update. If next_check is not sup‐
1461 plied, Conky defaults to 2. Max of 30 lines can be displayed, or
1462 until the text buffer is filled.
1463 hr (height)
1466 Horizontal line, height is the height in pixels.
1467 hwmon (dev) type n (factor offset)
1470 Hwmon sensor from sysfs (Linux 2.6). Parameter dev can be: 1)
1471 Number. e.g '1' means hwmon1. 2) Module name. e.g. 'k10temp'
1472 means the first hwmon device whose module name is 'k10temp. 3)
1473 Omitted. Then the first hwmon device (hwmon0) will be used. Pa‐
1474 rameter type is either 'in' or 'vol' meaning voltage; 'fan'
1475 meaning fan; 'temp' meaning temperature. Parameter n is number
1476 of the sensor. See /sys/class/hwmon/ on your local computer.
1477 The optional arguments 'factor' and 'offset' allow precalcula‐
1478 tion of the raw input, which is being modified as follows: 'in‐
1479 put = input * factor + offset'. Note that they have to be given
1480 as decimal values (i.e. contain at least one decimal place).
1481 iface (number)
1484 Display interface names starting from 1, eg ${iface 1}.
1485 i2c (dev) type n (factor offset)
1488 I2C sensor from sysfs (Linux 2.6). Parameter dev may be omitted
1489 if you have only one I2C device. Parameter type is either 'in'
1490 or 'vol' meaning voltage; 'fan' meaning fan; 'temp' meaning tem‐
1491 perature. Parameter n is number of the sensor. See
1492 /sys/bus/i2c/devices/ on your local computer. The optional argu‐
1493 ments 'factor' and 'offset' allow precalculation of the raw in‐
1494 put, which is being modified as follows: 'input = input * factor
1495 + offset'. Note that they have to be given as decimal values
1496 (i.e. contain at least one decimal place).
1497 i8k_ac_status
1500 If running the i8k kernel driver for Inspiron laptops, displays
1501 whether ac power is on, as listed in /proc/i8k (translated to
1502 human-readable). Beware that this is by default not enabled by
1503 i8k itself.
1504 i8k_bios
1507 If running the i8k kernel driver for Inspiron laptops, displays
1508 the bios version as listed in /proc/i8k.
1509 i8k_buttons_status
1512 If running the i8k kernel driver for Inspiron laptops, displays
1513 the volume buttons status as listed in /proc/i8k.
1514 i8k_cpu_temp
1517 If running the i8k kernel driver for Inspiron laptops, displays
1518 the cpu temperature in Celsius, as reported by /proc/i8k.
1519 i8k_left_fan_rpm
1522 If running the i8k kernel driver for Inspiron laptops, displays
1523 the left fan's rate of rotation, in revolutions per minute as
1524 listed in /proc/i8k. Beware, some laptops i8k reports these fans
1525 in reverse order.
1526 i8k_left_fan_status
1529 If running the i8k kernel driver for Inspiron laptops, displays
1530 the left fan status as listed in /proc/i8k (translated to human-
1531 readable). Beware, some laptops i8k reports these fans in re‐
1532 verse order.
1533 i8k_right_fan_rpm
1536 If running the i8k kernel driver for Inspiron laptops, displays
1537 the right fan's rate of rotation, in revolutions per minute as
1538 listed in /proc/i8k. Beware, some laptops i8k reports these fans
1539 in reverse order.
1540 i8k_right_fan_status
1543 If running the i8k kernel driver for Inspiron laptops, displays
1544 the right fan status as listed in /proc/i8k (translated to hu‐
1545 man-readable). Beware, some laptops i8k reports these fans in
1546 reverse order.
1547 i8k_serial
1550 If running the i8k kernel driver for Inspiron laptops, displays
1551 your laptop serial number as listed in /proc/i8k.
1552 i8k_version
1555 If running the i8k kernel driver for Inspiron laptops, displays
1556 the version formatting of /proc/i8k.
1557 ibm_brightness
1560 If running the IBM ACPI, displays the brigtness of the laptops's
1561 LCD (0-7).
1562 ibm_fan
1565 If running the IBM ACPI, displays the fan speed.
1566 ibm_temps N
1569 If running the IBM ACPI, displays the temperatures from the IBM
1570 temperature sensors (N=0..7) Sensor 0 is on the CPU, 3 is on the
1571 GPU.
1572 ibm_thinklight
1575 If running the IBM ACPI, displays the status of your Think‐
1576 Light™. Value is either 'on', 'off' or 'unknown'.
1577 ibm_volume
1580 If running the IBM ACPI, displays the "master" volume, con‐
1581 trolled by the volume keys (0-14).
1582 ical number file
1585 Shows title of event number 'number' in the ical (RFC 5545) file
1586 'file'. The events are first ordered by starting time, events
1587 that started in the past are ignored. The events that are shown
1588 are the VEVENTS, the title that is shown is the SUMMARY and the
1589 starting time used for sorting is DTSTART.
1590 irc server(:port) #channel (max_msg_lines)
1593 Shows everything that's being told in #channel on IRCserver
1594 'server'. TCP-port 6667 is used for the connection unless 'port'
1595 is specified. Shows everything since the last time or the last
1596 'max_msg_lines' entries if specified.
1597 iconv_start codeset_from codeset_to
1600 Convert text from one codeset to another using GNU iconv. Needs
1601 to be stopped with iconv_stop.
1602 iconv_stop
1605 Stop iconv codeset conversion.
1606 if_empty (var)
1609 if conky variable VAR is empty, display everything between
1610 $if_empty and the matching $endif.
1611 if_existing file (string)
1614 if FILE exists, display everything between if_existing and the
1615 matching $endif. The optional second parameter checks for FILE
1616 containing the specified string and prints everything between
1617 $if_existing and the matching $endif.
1618 if_gw if there is at least one default gateway, display everything be‐
1621 tween $if_gw and the matching $endif.
1622 if_match expression
1625 Evaluates the given boolean expression, printing everything be‐
1626 tween $if_match and the matching $endif depending on whether the
1627 evaluation returns true or not. Valid expressions consist of a
1628 left side, an operator and a right side. Left and right sides
1629 are being parsed for contained text objects before evaluation.
1630 Recognised left and right side types are:
1631 doubleArgument consists of only digits and a single dot.
1633 longArgument consists of only digits.
1634 stringArgument is enclosed in quotation marks. (")
1635 Valid operands are: '>', '<', '>=', '<=', '==', '!='.
1637 if_mixer_mute (mixer)
1640 If mixer exists, display everything between $if_mixer_mute and
1641 the matching $endif. If no mixer is specified, "Vol" is used.
1642 if_mounted (mountpoint)
1645 if MOUNTPOINT is mounted, display everything between $if_mounted
1646 and the matching $endif.
1647 if_mpd_playing
1650 if mpd is playing or paused, display everything between
1651 $if_mpd_playing and the matching $endif.
1652 if_pa_sink_muted
1655 If Pulseaudio's default sink is muted, display everything be‐
1656 tween $if_pa_sink_muted and the corresponding $else or $endif.
1657 if_running (process)
1660 If PROCESS is running, display everything between $if_running
1661 and the corresponding $else or $endif. Note that PROCESS may be
1662 either a full command line with arguments (without the directory
1663 prefix), or simply the name of an executable. For example, ei‐
1664 ther of the following will be true if there is a running process
1665 with the command line /usr/bin/conky -u 5:
1666 ${if_running conky -u 5}or ${if_running conky}
1668 It is important not to include trailing spaces. For example,
1670 ${if_running conky }will be false.
1671 if_smapi_bat_installed (INDEX)
1674 when using smapi, if the battery with index INDEX is installed,
1675 display everything between $if_smapi_bat_installed and the
1676 matching $endif.
1677 if_up (interface)
1680 if INTERFACE exists and is up, display everything between $if_up
1681 and the matching $endif.
1682 if_updatenr (updatenr)
1685 If it's the UPDATENR-th time that conky updates, display every‐
1686 thing between $if_updatenr and the matching $endif. The counter
1687 resets when the highest UPDATENR is reached. Example : "{$if_up‐
1688 datenr 1}foo$endif{$if_updatenr 2}bar$endif{$if_updatenr 4}$en‐
1689 dif" shows foo 25% of the time followed by bar 25% of the time
1690 followed by nothing the other half of the time.
1691 if_xmms2_connected
1694 Display everything between $if_xmms2_connected and the matching
1695 $endif if xmms2 is running.
1696 image <path to image> (-p x,y) (-s WxH) (-n) (-f interval)
1699 Renders an image from the path specified using Imlib2. Takes 4
1700 optional arguments: a position, a size, a no-cache switch, and a
1701 cache flush interval. Changing the x,y position will move the
1702 position of the image, and changing the WxH will scale the im‐
1703 age. If you specify the no-cache flag (-n), the image will not
1704 be cached. Alternately, you can specify the -f int switch to
1705 specify a cache flush interval for a particular image. Example:
1706 ${image /home/brenden/cheeseburger.jpg -p 20,20 -s 200x200} will
1707 render 'cheeseburger.jpg' at (20,20) scaled to 200x200 pixels.
1708 Conky does not make any attempt to adjust the position (or any
1709 other formatting) of images, they are just rendered as per the
1710 arguments passed. The only reason $image is part of the
1711 conky.text section, is to allow for runtime modifications,
1712 through $execp $lua_parse, or some other method.
1713 imap_messages (args)
1716 Displays the number of messages in your global IMAP inbox by de‐
1717 fault. You can define individual IMAP inboxes separately by
1718 passing arguments to this object. Arguments are: "host user pass
1719 [-i interval (in seconds)] [-f 'folder'] [-p port] [-e 'com‐
1720 mand'] [-r retries]". Default port is 143, default folder is
1721 'INBOX', default interval is 5 minutes, and default number of
1722 retries before giving up is 5. If the password is supplied as
1723 '*', you will be prompted to enter the password when Conky
1724 starts.
1725 imap_unseen (args)
1728 Displays the number of unseen messages in your global IMAP inbox
1729 by default. You can define individual IMAP inboxes separately by
1730 passing arguments to this object. Arguments are: "host user pass
1731 [-i interval (in seconds)] [-f 'folder'] [-p port] [-e 'com‐
1732 mand'] [-r retries]". Default port is 143, default folder is
1733 'INBOX', default interval is 5 minutes, and default number of
1734 retries before giving up is 5. If the password is supplied as
1735 '*', you will be prompted to enter the password when Conky
1736 starts.
1737 ioscheduler disk
1740 Prints the current ioscheduler used for the given disk name
1741 (i.e. e.g. "hda" or "sdb").
1742 journal lines (type)
1745 Displays last N lines of the systemd journal. The optional type
1746 can be 'user' or 'system' which will show only the user or sys‐
1747 tem journal respectively. By default, all journal lines visible
1748 to the user are shown. A maximum of 200 lines can be displayed,
1749 or until the text buffer is filled.
1750 kernel Kernel version.
1753 key_caps_lock
1756 An indicator for Capital Lock key.
1757 key_num_lock
1760 An indicator for Number Lock key.
1761 key_scroll_lock
1764 An indicator for Scrolling Lock key.
1765 keyboard_layout
1768 Display keyboard layout.
1769 version
1772 Git version number. DragonFly only.
1773 laptop_mode
1776 The value of /proc/sys/vm/laptop_mode.
1777 lines textfile
1780 Displays the number of lines in the given file.
1781 loadavg (1|2|3)
1784 System load average, 1 is for past 1 minute, 2 for past 5 min‐
1785 utes and 3 for past 15 minutes. Without argument, prints all
1786 three values separated by whitespace.
1787 loadgraph (height),(width) (gradient colour 1) (gradient colour 2)
1790 (scale) (-t) (-l)
1791 Load1 average graph, similar to xload, with optional colours in
1792 hex, minus the #. Uses a logarithmic scale (to see small num‐
1793 bers) when you use the -l switch. Takes the switch '-t' to use a
1794 temperature gradient, which makes the gradient values change de‐
1795 pending on the amplitude of a particular graph value (try it and
1796 see).
1797 lua function_name (function parameters)
1800 Executes a Lua function with given parameters, then prints the
1801 returned string. See also 'lua_load' on how to load scripts.
1802 Conky puts 'conky_' in front of function_name to prevent acci‐
1803 dental calls to the wrong function unless you put you place
1804 'conky_' in front of it yourself.
1805 lua_bar (height, width) function_name (function parameters)
1808 Executes a Lua function with given parameters and draws a bar.
1809 Expects result value to be an integer between 0 and 100. See al‐
1810 so 'lua_load' on how to load scripts. Conky puts 'conky_' in
1811 front of function_name to prevent accidental calls to the wrong
1812 function unless you put you place 'conky_' in front of it your‐
1813 self.
1814 lua_gauge (height, width) function_name (function parameters)
1817 Executes a Lua function with given parameters and draws a gauge.
1818 Expects result value to be an integer between 0 and 100. See al‐
1819 so 'lua_load' on how to load scripts. Conky puts 'conky_' in
1820 front of function_name to prevent accidental calls to the wrong
1821 function unless you put you place 'conky_' in front of it your‐
1822 self.
1823 lua_graph function_name (height),(width) (gradient colour 1) (gradient
1826 colour 2) (scale) (-t) (-l)
1827 Executes a Lua function with and draws a graph. Expects result
1828 value to be any number, and by default will scale to show the
1829 full range. See also 'lua_load' on how to load scripts. Takes
1830 the switch '-t' to use a temperature gradient, which makes the
1831 gradient values change depending on the amplitude of a particu‐
1832 lar graph value (try it and see). Conky puts 'conky_' in front
1833 of function_name to prevent accidental calls to the wrong func‐
1834 tion unless you put you place 'conky_' in front of it yourself.
1835 lua_parse function_name (function parameters)
1838 Executes a Lua function with given parameters as per $lua, then
1839 parses and prints the result value as per the syntax for the
1840 conky.text section. See also 'lua_load' on how to load scripts.
1841 Conky puts 'conky_' in front of function_name to prevent acci‐
1842 dental calls to the wrong function unless you put you place
1843 'conky_' in front of it yourself.
1844 machine
1847 Machine, e.g. i686, x86_64.
1848 mails (mailbox) (interval)
1851 Mail count in the specified mailbox or your mail spool if not.
1852 Both mbox and maildir type mailboxes are supported. You can use
1853 a program like fetchmail to get mails from some server using
1854 your favourite protocol. See also new_mails.
1855 mboxscan (-n number of messages to print) (-fw from width) (-sw subject
1858 width) mbox
1859 Print a summary of recent messages in an mbox format mailbox.
1860 mbox parameter is the filename of the mailbox (can be encapsu‐
1861 lated using '"', ie. ${mboxscan -n 10 "/home/brenden/some box"}
1862 mem Amount of memory in use.
1865 memwithbuffers
1868 Amount of memory in use, including that used by system buffers
1869 and caches.
1870 membar (height),(width)
1873 Bar that shows amount of memory in use.
1874 memwithbuffersbar (height),(width)
1877 Bar that shows amount of memory in use (including memory used by
1878 system buffers and caches).
1879 memwithbuffersgraph (height),(width) (gradient colour 1) (gradient
1882 colour 2) (scale) (-t) (-l)
1883 Memory usage graph including memory used by system buffers and
1884 cache. Uses a logarithmic scale (to see small numbers) when you
1885 use the -l switch. Takes the switch '-t' to use a temperature
1886 gradient, which makes the gradient values change depending on
1887 the amplitude of a particular graph value (try it and see).
1888 memdirty
1891 Amount of "dirty" memory. Linux only.
1892 memeasyfree
1895 Amount of free memory including the memory that is very easily
1896 freed (buffers/cache).
1897 memfree
1900 Amount of free memory.
1901 memgauge (height),(width)
1904 Gauge that shows amount of memory in use (see cpugauge).
1905 memgraph (height),(width) (gradient colour 1) (gradient colour 2)
1908 (scale) (-t) (-l)
1909 Memory usage graph. Uses a logarithmic scale (to see small num‐
1910 bers) when you use the -l switch. Takes the switch '-t' to use a
1911 temperature gradient, which makes the gradient values change de‐
1912 pending on the amplitude of a particular graph value (try it and
1913 see).
1914 memmax Total amount of memory.
1917 memperc
1920 Percentage of memory in use.
1921 mixer (device)
1924 Prints the mixer value as reported by the OS. On Linux, this
1925 variable uses the OSS emulation, so you need the proper kernel
1926 module loaded. Default mixer is "Vol", but you can specify one
1927 of the available OSS controls: "Vol", "Bass", "Trebl", "Synth",
1928 "Pcm", "Spkr", "Line", "Mic", "CD", "Mix", "Pcm2 ", "Rec",
1929 "IGain", "OGain", "Line1", "Line2", "Line3", "Digital1", "Digi‐
1930 tal2", "Digital3", "PhoneIn", "PhoneOut", "Video", "Radio" and
1931 "Monitor".
1932 mixerbar (device)
1935 Displays mixer value in a bar as reported by the OS. See docs
1936 for $mixer for details on arguments.
1937 mixerl (device)
1940 Prints the left channel mixer value as reported by the OS. See
1941 docs for $mixer for details on arguments.
1942 mixerlbar (device)
1945 Displays the left channel mixer value in a bar as reported by
1946 the OS. See docs for $mixer for details on arguments.
1947 mixerr (device)
1950 Prints the right channel mixer value as reported by the OS. See
1951 docs for $mixer for details on arguments.
1952 mixerrbar (device)
1955 Displays the right channel mixer value in a bar as reported by
1956 the OS. See docs for $mixer for details on arguments.
1957 moc_album
1960 Album of the current MOC song.
1961 moc_artist
1964 Artist of the current MOC song.
1965 moc_bitrate
1968 Bitrate in the current MOC song.
1969 moc_curtime
1972 Current time of the current MOC song.
1973 moc_file
1976 File name of the current MOC song.
1977 moc_rate
1980 Rate of the current MOC song.
1981 moc_song
1984 The current song name being played in MOC.
1985 moc_state
1988 Current state of MOC; playing, stopped etc.
1989 moc_timeleft
1992 Time left in the current MOC song.
1993 moc_title
1996 Title of the current MOC song.
1997 moc_totaltime
2000 Total length of the current MOC song.
2001 monitor
2004 Number of the monitor on which conky is running or the message
2005 "Not running in X" if this is the case.
2006 monitor_number
2009 Number of monitors or the message "Not running in X" if this is
2010 the case.
2011 mouse_speed
2014 Display mouse speed.
2015 mpd_album
2018 Album in current MPD song.
2019 mpd_artist
2022 Artist in current MPD song must be enabled at compile.
2023 mpd_albumartist
2026 Artist of the album of the current MPD song.
2027 mpd_bar (height),(width)
2030 Bar of mpd's progress.
2031 mpd_bitrate
2034 Bitrate of current song.
2035 mpd_date
2038 Date of current song.
2039 mpd_elapsed
2042 Song's elapsed time.
2043 mpd_file
2046 Prints the file name of the current MPD song.
2047 mpd_length
2050 Song's length.
2051 mpd_name
2054 Prints the MPD name field.
2055 mpd_percent
2058 Percent of song's progress.
2059 mpd_random
2062 Random status (On/Off).
2063 mpd_repeat
2066 Repeat status (On/Off).
2067 mpd_smart (max length)
2070 Prints the song name in either the form "artist - title" or file
2071 name, depending on whats available.
2072 mpd_status
2075 Playing, stopped, et cetera.
2076 mpd_title (max length)
2079 Title of current MPD song.
2080 mpd_track
2083 Prints the MPD track field.
2084 mpd_vol
2087 MPD's volume.
2088 mysql query
2091 Shows the first field of the first row of the result of the
2092 query.
2093 nameserver (index)
2096 Print a nameserver from /etc/resolv.conf. Index starts at and
2097 defaults to 0.
2098 new_mails (mailbox) (interval)
2101 Unread mail count in the specified mailbox or mail spool if not.
2102 Both mbox and maildir type mailboxes are supported.
2103 nodename
2106 Hostname.
2107 nodename_short
2110 Short hostname (same as 'hostname -s' shell command).
2111 no_update text
2114 Shows text and parses the vars in it, but doesn't update them.
2115 Use this for things that do not change while conky is running,
2116 like $machine, $conky_version,... By not updating this you can
2117 save some resources.
2118 nvidia argument (GPU_ID)
2121 Nvidia graphics card information via the XNVCtrl library.
2122 GPU_ID:Optional parameter to choose the GPU to be used as
2124 0,1,2,3,.. Default parameter is 0
2125 Possible arguments:(Temperatures are printed as float, all other
2127 values as integer. Bracketed arguments are aliases)
2128 gputemp( temp) GPU temperature
2130 gputempthreshold( threshold) Temperature threshold where the GPU
2131 will reduce it's clock speed
2132 ambienttemp( ambient) Ambient temperature outside the graphics
2133 card
2134 gpufreqcur( gpufreq) Current GPU clock speed
2135 gpufreqmin Minimum GPU clock speed
2136 gpufreqmax Maximum GPU clock speed
2137 memfreqcur( memfreq) Current memory clock speed
2138 memfreqmin Minimum memory clock speed
2139 memfreqmax Maximum memory clock speed
2140 mtrfreqcur( mtrfreq) Current memory transfer rate clock speed
2141 mtrfreqmin Minimum memory transfer rate clock speed
2142 mtrfreqmax Maximum memory transfer rate clock speed
2143 perflevelcur( perflevel) Current performance level
2144 perflevelmin Lowest performance level
2145 perflevelmax Highest performance level
2146 perfmode Performance mode
2147 gpuutil GPU utilization %
2148 membwutil Memory bandwidth utilization %
2149 videoutil Video engine utilization %
2150 pcieutil PCIe bandwidth utilization %
2151 memused( mem) Amount of used memory
2152 memfree( memavail) Amount of free memory
2153 memmax( memtotal) Total amount of memory
2154 memutil( memperc) Memory utilization %
2155 fanspeed Fan speed
2156 fanlevel Fan level %
2157 imagequality Image quality
2158 modelname name of the GPU card
2159 nvidiabar (height),(width) argument (GPU_ID)
2161 Same as nvidia, except it draws its output in a horizontal bar.
2162 The height and width parameters are optional, and default to the
2163 default_bar_height and default_bar_width config settings, re‐
2164 spectively.
2165 GPU_ID:Optional parameter to choose the GPU to be used as
2167 0,1,2,3,.. Default parameter is 0
2168 Note the following arguments are incompatible: gputempthreshold(
2170 threshold)
2171 gpufreqmin
2172 gpufreqmax
2173 memfreqmin
2174 memfreqmax
2175 mtrfreqmin
2176 mtrfreqmax
2177 perflevelmin
2178 perflevelmax
2179 perfmode
2180 memtotal( memmax)
2181 fanspeed
2182 nvidiagauge (height),(width) argument (GPU_ID)
2184 Same as nvidiabar, except a round gauge (much like a vehicle
2185 speedometer). The height and width parameters are optional, and
2186 default to the default_gauge_height and default_gauge_width con‐
2187 fig settings, respectively.
2188 GPU_ID:Optional parameter to choose the GPU to be used as
2190 0,1,2,3,.. Default parameter is 0
2191 For possible arguments see nvidia and nvidiabar.
2193 nvidiagraph argument (height),(width) (gradient color 1) (gradient col‐
2195 or 2) (scale) (-t) (-l) GPU_ID
2196 Same as nvidiabar, except a horizontally scrolling graph with
2197 values from 0-100 plotted on the vertical axis. The height and
2198 width parameters are optional, and default to the de‐
2199 fault_graph_height and default_graph_width config settings, re‐
2200 spectively.
2201 GPU_ID:NOT optional. This parameter allows to choose the GPU to
2203 be used as 0,1,2,3,..
2204 For possible arguments see nvidia and nvidiabar. To learn more
2206 about the -t -l and gradient color options, see execgraph.
2207 offset (pixels)
2209 Move text over by N pixels. See also $voffset.
2210 outlinecolor (color)
2213 Change outline color.
2214 password (length)
2217 Generate random passwords.
2218 pa_sink_volume
2221 Pulseaudio's default sink volume percentage.
2222 pa_sink_volumebar
2225 Pulseaudio's default sink volume bar.
2226 pa_sink_description
2229 Pulseaudio's default sink description.
2230 pa_sink_active_port_name
2233 Pulseaudio's default sink active port name.
2234 pa_sink_active_port_description
2237 Pulseaudio's default sink active port description.
2238 pa_card_name
2241 Pulseaudio's default card name.
2242 pa_card_active_profile
2245 Pulseaudio's default card active profile.
2246 pb_battery item
2249 If running on Apple powerbook/ibook, display information on bat‐
2250 tery status. The item parameter specifies, what information to
2251 display. Exactly one item must be specified. Valid items are:
2252 status Display if battery is fully charged, charging, discharg‐
2254 ing or absent (running on AC)
2255 percent Display charge of battery in percent, if charging or
2256 discharging. Nothing will be displayed, if battery is fully
2257 charged or absent.
2258 time Display the time remaining until the battery will be fully
2259 charged or discharged at current rate. Nothing is displayed, if
2260 battery is absent or if it's present but fully charged and not
2261 discharging.
2262 pid_chroot pid
2265 Directory used as rootdirectory by the process (this will be "/"
2266 unless the process did a chroot syscall).
2267 pid_cmdline pid
2270 Command line this process was invoked with.
2271 pid_cwd pid
2274 Current working directory of the process.
2275 pid_environ pid varname
2278 Contents of a environment-var of the process.
2279 pid_environ_list pid
2282 List of environment-vars that the process can see.
2283 pid_exe pid
2286 Path to executed command that started the process.
2287 pid_nice pid
2290 The nice value of the process.
2291 pid_openfiles pid
2294 List of files that the process has open.
2295 pid_parent pid
2298 The pid of the parent of the process.
2299 pid_priority pid
2302 The priority of the process (see 'priority' in "man 5 proc").
2303 pid_read pid
2306 Total number of bytes read by the process.
2307 pid_state pid
2310 State of the process.
2311 pid_state_short pid
2314 One of the chars in "RSDZTW" representing the state of the
2315 process where R is running, S is sleeping in an interruptible
2316 wait, D is waiting in uninterruptible disk sleep, Z is zombie, T
2317 is traced or stopped (on a signal), and W is paging.
2318 pid_stderr pid
2321 Filedescriptor binded to the STDERR of the process.
2322 pid_stdin pid
2325 Filedescriptor binded to the STDIN of the process.
2326 pid_stdout pid
2329 Filedescriptor binded to the STDOUT of the process.
2330 pid_threads pid
2333 Number of threads in process containing this thread.
2334 pid_thread_list pid
2337 List with pid's from threads from this process.
2338 pid_time_kernelmode pid
2341 Amount of time that the process has been scheduled in kernel
2342 mode in seconds.
2343 pid_time_usermode pid
2346 Amount of time that the process has been scheduled in user mode
2347 in seconds.
2348 pid_time pid
2351 Sum of $pid_time_kernelmode and $pid_time_usermode.
2352 pid_uid pid
2355 The real uid of the process.
2356 pid_euid pid
2359 The effective uid of the process.
2360 pid_suid pid
2363 The saved set uid of the process.
2364 pid_fsuid pid
2367 The file system uid of the process.
2368 pid_gid pid
2371 The real gid of the process.
2372 pid_egid pid
2375 The effective gid of the process.
2376 pid_sgid pid
2379 The saved set gid of the process.
2380 pid_fsgid pid
2383 The file system gid of the process.
2384 pid_vmpeak pid
2387 Peak virtual memory size of the process.
2388 pid_vmsize pid
2391 Virtual memory size of the process.
2392 pid_vmlck pid
2395 Locked memory size of the process.
2396 pid_vmhwm pid
2399 Peak resident set size ("high water mark") of the process.
2400 pid_vmrss pid
2403 Resident set size of the process.
2404 pid_vmdata pid
2407 Data segment size of the process.
2408 pid_vmstk pid
2411 Stack segment size of the process.
2412 pid_vmexe pid
2415 Text segment size of the process.
2416 pid_vmlib pid
2419 Shared library code size of the process.
2420 pid_vmpte pid
2423 Page table entries size of the process.
2424 pid_write pid
2427 Total number of bytes written by the process.
2428 platform (dev) type n (factor offset)
2431 Platform sensor from sysfs (Linux 2.6). Parameter dev may be
2432 omitted if you have only one platform device. Platform type is
2433 either 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp'
2434 meaning temperature. Parameter n is number of the sensor. See
2435 /sys/bus/platform/devices/ on your local computer. The optional
2436 arguments 'factor' and 'offset' allow precalculation of the raw
2437 input, which is being modified as follows: 'input = input * fac‐
2438 tor + offset'. Note that they have to be given as decimal values
2439 (i.e. contain at least one decimal place).
2440 pop3_unseen (args)
2443 Displays the number of unseen messages in your global POP3 inbox
2444 by default. You can define individual POP3 inboxes separately by
2445 passing arguments to this object. Arguments are: "host user pass
2446 [-i interval (in seconds)] [-p port] [-e 'command'] [-r re‐
2447 tries]". Default port is 110, default interval is 5 minutes, and
2448 default number of retries before giving up is 5. If the password
2449 is supplied as '*', you will be prompted to enter the password
2450 when Conky starts.
2451 pop3_used (args)
2454 Displays the amount of space (in MiB, 2^20) used in your global
2455 POP3 inbox by default. You can define individual POP3 inboxes
2456 separately by passing arguments to this object. Arguments are:
2457 "host user pass [-i interval (in seconds)] [-p port] [-e 'com‐
2458 mand'] [-r retries]". Default port is 110, default interval is 5
2459 minutes, and default number of retries before giving up is 5. If
2460 the password is supplied as '*', you will be prompted to enter
2461 the password when Conky starts.
2462 processes
2465 Total processes (sleeping and running).
2466 read_tcp (host) port
2469 Connects to a tcp port on a host (default is localhost), reads
2470 every char available at the moment and shows them.
2471 read_udp (host) port
2474 Connects to a udp port on a host (default is localhost), reads
2475 every char available at the moment and shows them.
2476 replied_mails (maildir) (interval)
2479 Number of mails marked as replied in the specified mailbox or
2480 mail spool if not. Only maildir type mailboxes are supported,
2481 mbox type will return -1.
2482 rss uri interval_in_seconds action (num_par (spaces_in_front))
2485 Download and parse RSS feeds. The interval may be a (floating
2486 point) value greater than 0. Action may be one of the following:
2487 feed_title, item_title (with num par), item_desc (with num par)
2488 and item_titles (when using this action and spaces_in_front is
2489 given conky places that many spaces in front of each item). This
2490 object is threaded, and once a thread is created it can't be ex‐
2491 plicitly destroyed. One thread will run for each URI specified.
2492 You can use any protocol that Curl supports.
2493 running_processes
2496 Running processes (not sleeping). Requires Linux 2.6.
2497 running_threads
2500 Number of running (runnable) threads. Linux only.
2501 scroll (direction) length (step) (interval) text
2504 Scroll 'text' by 'step' characters to the left or right (set
2505 'direction' to 'left' or 'right' or 'wait') showing 'length'
2506 number of characters at the same time. The text may also contain
2507 variables. 'step' is optional and defaults to 1 if not set.
2508 'direction' is optional and defaults to left if not set. When
2509 direction is 'wait' then text will scroll left and wait for 'in‐
2510 terval' itertations at the beginning and end of the text. If a
2511 var creates output on multiple lines then the lines are placed
2512 behind each other separated with a '|'-sign. If you change the
2513 textcolor inside $scroll it will automatically have it's old
2514 value back at the end of $scroll. The end and the start of text
2515 will be separated by 'length' number of spaces unless direction
2516 is 'wait'.
2517 seen_mails (maildir) (interval)
2520 Number of mails marked as seen in the specified mailbox or mail
2521 spool if not. Only maildir type mailboxes are supported, mbox
2522 type will return -1.
2523 sip_status (switch)
2526 Prints info regarding System Integrity Protection (SIP) on mac‐
2527 OS. If no switch is provided, prints SIP status (enabled / dis‐
2528 abled), else, status of the specific SIP feature corresponding
2529 to the switch provided. Below are shown the available switches:
2530 SWITCH--------------------------RE‐
2531 SULT--------------------------STATUS 0 apple internal YES/NO 1
2532 forbid untrusted kexts YES/NO 2 forbid task-for-pid YES/NO 3 re‐
2533 strict filesystem YES/NO 4 forbid kernel-debugger YES/NO 5 re‐
2534 strict dtrace YES/NO 6 restrict nvram YES/NO 7 forbid device-
2535 configuration YES/NO 8 forbid any-recovery-os YES/NO 9 forbid
2536 user-approved-kexts YES/NO a uses unsupported configuration? (*)
2537 (*): If yes, prints "unsupported configuration, beware!" Else,
2538 prints "configuration is ok".
2539 ----------------------------------------------------------------------
2540 USAGE: conky -t '${sip_status}' # print SIP status conky -t
2541 '${sip_status 0}' # print allows apple-internal? Yes or No?
2542 NOTES: * Available for all macOS versions (even the ones prior
2543 El Capitan where SIP was first introduced) * If run on versions
2544 prior El Capitan SIP is unavailable, so all you will get is "un‐
2545 supported".
2546 shadecolor (color)
2549 Change shading color.
2550 smapi (ARGS)
2553 when using smapi, display contents of the /sys/devices/plat‐
2554 form/smapi directory. ARGS are either '(FILENAME)' or 'bat (IN‐
2555 DEX) (FILENAME)' to display the corresponding files' content.
2556 This is a very raw method of accessing the smapi values. When
2557 available, better use one of the smapi_* variables instead.
2558 smapi_bat_bar (INDEX),(height),(width)
2561 when using smapi, display the remaining capacity of the battery
2562 with index INDEX as a bar.
2563 smapi_bat_perc (INDEX)
2566 when using smapi, display the remaining capacity in percent of
2567 the battery with index INDEX. This is a separate variable be‐
2568 cause it supports the 'use_spacer' configuration option.
2569 smapi_bat_power INDEX
2572 when using smapi, display the current power of the battery with
2573 index INDEX in watt. This is a separate variable because the
2574 original read out value is being converted from mW. The sign of
2575 the output reflects charging (positive) or discharging (nega‐
2576 tive) state.
2577 smapi_bat_temp INDEX
2580 when using smapi, display the current temperature of the battery
2581 with index INDEX in degree Celsius. This is a separate variable
2582 because the original read out value is being converted from mil‐
2583 li degree Celsius.
2584 sony_fanspeed
2587 Displays the Sony VAIO fanspeed information if sony-laptop ker‐
2588 nel support is enabled. Linux only.
2589 start_case text
2592 All words capitalized regardless.
2593 stippled_hr (space)
2596 Stippled (dashed) horizontal line.
2597 stock symbol data
2600 Displays the data of a stock symbol. The following data is sup‐
2601 ported: adv(Average Daily Volume), ask, asksize, bid, askrt(ask
2602 realtime), bidrt(bid realtime), bookvalue, bidsize, change, com‐
2603 mission, changert(change realtime), ahcrt(After Hours Change re‐
2604 altime), ds(dividend/share), ltd(Last Trade Date), tradedate,
2605 es(earnings/share), ei(error indication), epsecy(EPS Estimate
2606 Current Year), epseny(EPS Estimate Next Year), epsenq(EPS Esti‐
2607 mate Next Quarter), floatshares, dayslow, dayshigh, 52weeklow,
2608 52weekhigh, hgp(Holdings Gain Percent), ag(Annualized Gain),
2609 hg(Holdings Gain), hgprt(Holdings Gain Percent realtime),
2610 hgrt(Holdings Gain realtime), moreinfo, obrt(Order Book real‐
2611 time), mc(Market Capitalization), mcrt(Market Cap realtime),
2612 ebitda, c52wlow(Change From 52-week Low), pc52wlow(Percent
2613 Change From 52-week Low), cprt(change percent realtime),
2614 lts(Last Trade Size), c52whigh(Change from 52-week high),
2615 pc52whigh(percent change from 52-week high), ltp(last trade
2616 price), hl(high limit), ll(low limit), dr(day's range), dr‐
2617 rt(day's range realtime), 50ma(50-day Moving Average),
2618 200ma(200-day Moving Average), c200ma(Change From 200-day Moving
2619 Average), pc200ma(Percent Change From 200-day Moving Average),
2620 c50ma(Change From 50-day Moving Average), pc50ma(Percent Change
2621 From 50-day Moving Average), name, notes, open, pc(previous
2622 close), pricepaid, cip(change in percent), ps(price/sales),
2623 pb(price/book), edv(Ex-Dividend Date), per(P/E Ratio), dpd(Divi‐
2624 dend Pay Date), perrt(P/E Ratio realtime), pegr(PEG Ratio),
2625 pepsecy(Price/EPS Estimate Current Year), pepseny(Price/EPS Es‐
2626 timate Next Year), symbol, sharesowned, shortratio, ltt(Last
2627 Trade Time), tradelinks, tt(Ticker Trend), 1ytp(1 yr Target
2628 Price), volume, hv(Holdings Value), hvrt(Holdings Value real‐
2629 time), 52weekrange, dvc(Day's Value Change), dvcrt(Day's Value
2630 Change realtime), se(Stock Exchange), dy(Dividend Yield).
2631 swap Amount of swap in use.
2634 swapbar (height),(width)
2637 Bar that shows amount of swap in use.
2638 swapfree
2641 Amount of free swap.
2642 swapmax
2645 Total amount of swap.
2646 swapperc
2649 Percentage of swap in use.
2650 sysname
2653 System name, e.g. Linux.
2654 sysctlbyname (name)
2657 Print sysctl value by name. FreeBSD only.
2658 tab (width, (start))
2661 Puts a tab of the specified width, starting from column 'start'.
2662 The unit is pixels for both arguments.
2663 tail logfile lines (next_check)
2666 Displays last N lines of supplied text file. The file is checked
2667 every 'next_check' update. If next_check is not supplied, Conky
2668 defaults to 2. Max of 30 lines can be displayed, or until the
2669 text buffer is filled.
2670 tcp_ping host (port)
2673 Displays the number of microseconds it takes to get a reply on a
2674 ping to to tcp 'port' on 'host'. 'port' is optional and has 80
2675 as default. This works on both open and closed ports, just make
2676 sure that the port is not behind a firewall or you will get
2677 'down' as answer. It's best to test a closed port instead of an
2678 open port, you will get a quicker response.
2679 tcp_portmon port_begin port_end item (index)
2682 TCP port (both IPv6 and IPv4) monitor for specified local ports.
2683 Port numbers must be in the range 1 to 65535. Valid items are:
2684 count Total number of connections in the range
2686 rip Remote ip address
2687 rhost Remote host name
2688 rport Remote port number
2689 rservice Remote service name from /etc/services
2690 lip Local ip address
2691 lhost Local host name
2692 lport Local port number
2693 lservice Local service name from /etc/services
2694 The connection index provides you with access to each connection
2696 in the port monitor. The monitor will return information for in‐
2697 dex values from 0 to n-1 connections. Values higher than n-1 are
2698 simply ignored. For the "count" item, the connection index must
2699 be omitted. It is required for all other items.
2700 Examples:
2702 ${tcp_portmon 6881 6999 count} Displays the number of connec‐
2704 tions in the bittorrent port range
2705 ${tcp_portmon 22 22 rip 0} Displays the remote host ip of the
2706 first sshd connection
2707 ${tcp_portmon 22 22 rip 9} Displays the remote host ip of the
2708 tenth sshd connection
2709 ${tcp_portmon 1 1024 rhost 0} Displays the remote host name of
2710 the first connection on a privileged port
2711 ${tcp_portmon 1 1024 rport 4} Displays the remote host port of
2712 the fifth connection on a privileged port
2713 ${tcp_portmon 1 65535 lservice 14} Displays the local service
2714 name of the fifteenth connection in the range of all ports
2715 Note that port monitor variables which share the same port range
2717 actually refer to the same monitor, so many references to a sin‐
2718 gle port range for different items and different indexes all use
2719 the same monitor internally. In other words, the program avoids
2720 creating redundant monitors.
2721 templateN (arg1) (arg2) (arg3 ...)
2723 Evaluate the content of the templateN configuration variable
2724 (where N is a value between 0 and 9, inclusively), applying sub‐
2725 stitutions as described in the documentation of the correspond‐
2726 ing configuration variable. The number of arguments is optional,
2727 but must match the highest referred index in the template. You
2728 can use the same special sequences in each argument as the ones
2729 valid for a template definition, e.g. to allow an argument to
2730 contain a whitespace. Also simple nesting of templates is possi‐
2731 ble this way.
2732 Here are some examples of template definitions, note they are
2734 placed between [[ ... ]] instead of ' ... ':
2735 template0 = [[$\1\2]]
2737 template1 = [[\1: ${fs_used \2} / ${fs_size \2}]]
2738 template2 = [[\1 \2]]
2739 The following list shows sample usage of the templates defined
2741 above, with the equivalent syntax when not using any template at
2742 all:
2743 using template same without template
2745 ────────────────────────────────────────────────────────
2746 ${template0 node name} $nodename
2747 ${template1 root /} root: ${fs_free /} /
2748 ${fs_size /}
2749 ${template1 ${template2\ disk root: ${fs_free /} /
2750 disk\ root} /} ${fs_size /}
2751 texeci interval command
2753 Runs a command at an interval inside a thread and displays the
2754 output. Same as $execi, except the command is run inside a
2755 thread. Use this if you have a slow script to keep Conky updat‐
2756 ing. You should make the interval slightly longer than the time
2757 it takes your script to execute. For example, if you have a
2758 script that take 5 seconds to execute, you should make the in‐
2759 terval at least 6 seconds. See also $execi. This object will
2760 clean up the thread when it is destroyed, so it can safely be
2761 used in a nested fashion, though it may not produce the desired
2762 behaviour if used this way.
2763 texecpi interval command
2766 Same as execpi, except the command is run inside a thread.
2767 threads
2770 Total threads.
2771 time (format)
2774 Local time, see "man strftime" to get more information about
2775 format.
2776 to_bytes size
2779 If 'size' is a number followed by a size-unit (kilo‐
2780 byte,mb,GiB,...) then it converts the size to bytes and shows it
2781 without unit, otherwise it just shows 'size'.
2782 top type num
2785 This takes arguments in the form:top (name) (number) Basically,
2786 processes are ranked from highest to lowest in terms of cpu us‐
2787 age, which is what (num) represents. The types are: "name",
2788 "pid", "cpu", "mem", "mem_res", "mem_vsize", "time", "uid", "us‐
2789 er", "io_perc", "io_read" and "io_write". There can be a max of
2790 10 processes listed.
2791 top_io type num
2794 Same as top, except sorted by the amount of I/O the process has
2795 done during the update interval.
2796 top_mem type num
2799 Same as top, except sorted by mem usage instead of cpu.
2800 top_time type num
2803 Same as top, except sorted by total CPU time instead of current
2804 CPU usage.
2805 totaldown (net)
2808 Total download, overflows at 4 GB on Linux with 32-bit arch and
2809 there doesn't seem to be a way to know how many times it has al‐
2810 ready done that before conky has started.
2811 totalup (net)
2814 Total upload, this one too, may overflow.
2815 trashed_mails (maildir) (interval)
2818 Number of mails marked as trashed in the specified mailbox or
2819 mail spool if not. Only maildir type mailboxes are supported,
2820 mbox type will return -1.
2821 tztime (timezone (format))
2824 Local time for specified timezone, see man strftime to get more
2825 information about format. The timezone argument is specified in
2826 similar fashion as TZ environment variable. For hints, look in
2827 /usr/share/zoneinfo. e.g. US/Pacific, Europe/Zurich, etc.
2828 gid_name gid
2831 Name of group with this gid.
2832 uid_name uid
2835 Username of user with this uid.
2836 unflagged_mails (maildir) (interval)
2839 Number of mails not marked as flagged in the specified mailbox
2840 or mail spool if not. Only maildir type mailboxes are supported,
2841 mbox type will return -1.
2842 unforwarded_mails (maildir) (interval)
2845 Number of mails not marked as forwarded in the specified mailbox
2846 or mail spool if not. Only maildir type mailboxes are supported,
2847 mbox type will return -1.
2848 unreplied_mails (maildir) (interval)
2851 Number of mails not marked as replied in the specified mailbox
2852 or mail spool if not. Only maildir type mailboxes are supported,
2853 mbox type will return -1.
2854 unseen_mails (maildir) (interval)
2857 Number of new or unseen mails in the specified mailbox or mail
2858 spool if not. Only maildir type mailboxes are supported, mbox
2859 type will return -1.
2860 updates Number of updates
2863 for debugging.
2864 upspeed (net)
2867 Upload speed in suitable IEC units.
2868 upspeedf (net)
2871 Upload speed in KiB with one decimal.
2872 upspeedgraph (netdev) (height),(width) (gradient colour 1) (gradient
2875 colour 2) (scale) (-t) (-l)
2876 Upload speed graph, colours defined in hex, minus the #. If
2877 scale is non-zero, it becomes the scale for the graph. Uses a
2878 logarithmic scale (to see small numbers) when you use the -l
2879 switch. Takes the switch '-t' to use a temperature gradient,
2880 which makes the gradient values change depending on the ampli‐
2881 tude of a particular graph value (try it and see).
2882 uptime Uptime.
2885 uptime_short
2888 Uptime in a shorter format.
2889 user_names
2892 Lists the names of the users logged in.
2893 user_number
2896 Number of users logged in.
2897 user_terms
2900 Lists the consoles in use.
2901 user_times
2904 Lists how long users have been logged in for.
2905 user_time console
2908 Lists how long the user for the given console has been logged in
2909 for.
2910 utime (format)
2913 Display time in UTC (universal coordinate time).
2914 v6addrs (-n) (-s) (interface)
2917 IPv6 addresses for an interface, followed by netmask if -n is
2918 specified and scope with -s. Scopes are Global(G), Host-lo‐
2919 cal(H), Link-local(L), Site-local(S), Compat(C) and Unspeci‐
2920 fied(/). Linux only.
2921 voffset (pixels)
2924 Change vertical offset by N pixels. Negative values will cause
2925 text to overlap. See also $offset.
2926 voltage_mv (n)
2929 Returns CPU #n's voltage in mV. CPUs are counted from 1. If
2930 omitted, the parameter defaults to 1.
2931 voltage_v (n)
2934 Returns CPU #n's voltage in V. CPUs are counted from 1. If omit‐
2935 ted, the parameter defaults to 1.
2936 weather URI locID data_type (interval_in_minutes)
2939 Download, parse and display METAR data.
2940 'URI' must be a valid METAR URI.
2942 http://tgftp.nws.noaa.gov/data/observations/metar/stations/
2944 'locID' must be a valid location identifier for the required
2946 uri. For the NOAA site this must be a valid ICAO (see for in‐
2947 stance https://pilotweb.nas.faa.gov/qryhtml/icao/). For the
2948 weather.com site this must be a valid location ID (see for in‐
2949 stance http://aspnetresources.com/tools/locid.aspx).
2950 'data_type' must be one of the following:
2952 last_update The date and time stamp of the data. The result de‐
2954 pends on the URI used. For the NOAA site it is date (yyyy/mm/dd)
2955 and UTC time. For the weather.com one it is date ([m]m/[d]d/yy)
2956 and Local Time of the station.
2957 temperature
2958 Air temperature (you can use the 'temperature_unit' config set‐
2960 ting to change units)
2961 cloud_cover
2962 The highest cloud cover status
2964 pressure
2965 Air pressure in millibar
2967 wind_speed
2968 Wind speed in km/h
2970 wind_dir
2971 Wind direction
2973 wind_dir_DEG
2974 Compass wind direction
2976 humidity
2977 Relative humidity in %
2979 weather
2980 Any relevant weather event (rain, snow, etc.). This is not used
2982 if you are querying the weather.com site since this data is ag‐
2983 gregated into the cloud_cover one
2984 icon
2985 Weather icon (only for www.weather.com). Can be used together
2987 with the icon kit provided upon registering to their service.
2988 'delay_in_minutes' (optional, default 30) cannot be less than 30
2990 minutes.
2991 This object is threaded, and once a thread is created it can't
2993 be explicitly destroyed. One thread will run for each URI speci‐
2994 fied.
2995 Note that these variables are still EXPERIMENTAL and can be sub‐
2997 ject to many future changes.
2998 weather_forecast URI locID day data_type (interval_in_minutes)
3000 Download, parse and display weather forecast data for a given
3001 day (daytime only).
3002 'locID', see 'weather' above.
3004 'day' is a number from 0 (today) to 4 (3 days after tomorrow).
3006 'data_type' must be one of the following:
3008 day Day of the week
3010 date Date, in the form MMM DD (ie. Jul 14)
3011 low Minimun temperature (you can use the 'temperature_unit' con‐
3012 fig setting to change units)
3013 hi Maximum temperature (you can use the 'temperature_unit' con‐
3014 fig setting to change units)
3015 icon Weather icon. Can be used together with the icon kit pro‐
3016 vided upon registering to the weather.com service
3017 forecast Weather forecast (sunny, rainy, etc.)
3018 wind_speed Wind speed in km/h
3019 wind_dir Wind direction
3020 wind_dir_DEG Compass wind direction
3021 humidity Relative humidity in %
3022 precipitation Probability of having a precipitation (in %)
3023 'delay_in_minutes' (optional, default 210) cannot be lower than
3025 210 min.
3026 This object is threaded, and once a thread is created it can't
3028 be explicitly destroyed. One thread will run for each URI speci‐
3029 fied. You can use any protocol that Curl supports.
3030 Note that these variables are still EXPERIMENTAL and can be sub‐
3032 ject to many future changes.
3033 wireless_ap (net)
3035 Wireless access point MAC address. Linux only.
3036 wireless_bitrate (net)
3039 Wireless bitrate (ie 11 Mb/s). Linux only.
3040 wireless_channel (net)
3043 WLAN channel on which device 'net' is listening.
3044 wireless_essid (net)
3047 Wireless access point ESSID. Linux only.
3048 wireless_freq (net)
3051 Frequency on which device 'net' is listening.
3052 wireless_link_bar (height),(width) (net)
3055 Wireless link quality bar. Linux only.
3056 wireless_link_qual (net)
3059 Wireless link quality. Linux only.
3060 wireless_link_qual_max (net)
3063 Wireless link quality maximum value. Linux only.
3064 wireless_link_qual_perc (net)
3067 Wireless link quality in percents. Linux only.
3068 wireless_mode (net)
3071 Wireless mode (Managed/Ad-Hoc/Master). Linux only.
3072 words textfile
3075 Displays the number of words in the given file.
3076 xmms2_album
3079 Album in current XMMS2 song.
3080 xmms2_artist
3083 Artist in current XMMS2 song.
3084 xmms2_bar (height),(width)
3087 Bar of XMMS2's progress.
3088 xmms2_bitrate
3091 Bitrate of current song.
3092 xmms2_comment
3095 Comment in current XMMS2 song.
3096 xmms2_date
3099 Returns song's date.
3100 xmms2_duration
3103 Duration of current song.
3104 xmms2_elapsed
3107 Song's elapsed time.
3108 xmms2_genre
3111 Genre in current XMMS2 song.
3112 xmms2_id
3115 XMMS2 id of current song.
3116 xmms2_percent
3119 Percent of song's progress.
3120 xmms2_playlist
3123 Returns the XMMS2 playlist.
3124 xmms2_size
3127 Size of current song.
3128 xmms2_smart
3131 Prints the song name in either the form "artist - title" or file
3132 name, depending on whats available.
3133 xmms2_status
3136 XMMS2 status (Playing, Paused, Stopped, or Disconnected).
3137 xmms2_timesplayed
3140 Number of times a song was played (presumably).
3141 xmms2_title
3144 Title in current XMMS2 song.
3145 xmms2_tracknr
3148 Track number in current XMMS2 song.
3149 xmms2_url
3152 Full path to current song.
3153
3156 Conky features a Lua Programming API, and also ships with Lua bindings
3157 for some useful libraries. Note that the bindings require tolua++,
3158 which currently only compiles against Lua 5.1.
3159 To use Lua Conky, you first need to make sure you have a version of
3161 Conky with Lua support enabled (``conky -v'' will report this). Conky
3162 defines certain global functions and variables which can be accessed
3163 from Lua code running in Conky. Scripts must first be loaded using the
3164 lua_load configuration option. You then call functions in Lua via
3165 Conky's $lua, $lua_read, and Lua hooks.
3166 Be careful when creating threaded objects through the Lua API. You
3168 could wind up with a whole bunch of threads running if a thread is cre‐
3169 ated with each iteration.
3170 At this time, the Lua API should not be considered stable and may
3172 change drastically from one release to another as it matures.
3173 NOTE: In order to accommodate certain features in the cairo library's
3175 API, Conky will export a few additional functions for the creation of
3176 certain structures. These are documented below.
3177 conky_parse(string) function
3179 This function takes a string that is evaluated as per Conky's
3180 TEXT section, and then returns a string with the result.
3181 conky_set_update_interval(number) function
3183 Sets Conky's update interval (in seconds) to 'number'.
3184 conky_window table
3186 This table contains some information about Conky's window. The
3187 following table describes the values contained:
3188 drawable Window's drawable (Xlib Drawable), requires Lua extras
3190 enabled at compile time.
3191 visual Window's visual (Xlib Visual), requires Lua extras en‐
3192 abled at compile time.
3193 display Window's display (Xlib Display), requires Lua extras en‐
3194 abled at compile time.
3195 width Window width (in pixels).
3196 height Window height (in pixels).
3197 border_inner_margin Window's inner border margin (in pixels).
3198 border_outer_margin Window's outer border margin (in pixels).
3199 border_width Window's border width (in pixels).
3200 text_start_x The x component of the starting coordinate of text
3201 drawing.
3202 text_start_y The y component of the starting coordinate of text
3203 drawing.
3204 text_width The width of the text drawing region.
3205 text_height The height of the text drawing region.
3206 NOTE: This table is only defined when X support is enabled.
3208 conky_info table
3210 This table contains some information about Conky's internal da‐
3211 ta. The following table describes the values contained:
3212 update_interval Conky's update interval (in seconds).
3214 conky_build_info string
3216 A string containing the build info for this particular instance
3217 of Conky, including the version, build date, and architecture.
3218 conky_build_date string
3220 A string containing the build date for this particular instance
3221 of Conky.
3222 conky_build_arch string
3224 A string containing the build architecture for this particular
3225 instance of Conky.
3226 conky_version string
3228 A string containing the version of the current instance of
3229 Conky.
3230 conky_config string
3232 A string containing the path of the current Conky configuration
3233 file.
3234 cairo_text_extents_t:create() function
3236 Call this function to return a new cairo_text_extents_t struc‐
3237 ture. A creation function for this structure is not provided by
3238 the cairo API. After calling this, you should use tolua.takeown‐
3239 ership() on the return value to ensure ownership is passed prop‐
3240 erly.
3241 cairo_font_extents_t:create() function
3243 Call this function to return a new cairo_font_extents_t struc‐
3244 ture. A creation function for this structure is not provided by
3245 the cairo API. After calling this, you should use tolua.takeown‐
3246 ership() on the return value to ensure ownership is passed prop‐
3247 erly.
3248 cairo_matrix_t:create() function
3250 Call this function to return a new cairo_matrix_t structure. A
3251 creation function for this structure is not provided by the
3252 cairo API. After calling this, you should use tolua.takeowner‐
3253 ship() on the return value to ensure ownership is passed proper‐
3254 ly.
3255 cairo_text_extents_t:destroy(structure) function
3257 Call this function to free memory allocated by cairo_text_ex‐
3258 tents_t:create.
3259 cairo_font_extents_t:destroy(structure) function
3261 Call this function to free memory allocated by cairo_font_ex‐
3262 tents_t:create.
3263 cairo_matrix_t:destroy(structure) function
3265 Call this function to free memory allocated by cairo_ma‐
3266 trix_t:create.
3267
3269 conky -t '${time %D %H:%M}' -o -u 30
3270 Start Conky in its own window with date and clock as text and 30
3271 sec update interval.
3272 conky -a top_left -x 5 -y 500 -d
3274 Start Conky to background at coordinates (5, 500).
3275 conky -C > ~/.config/conky/conky.conf
3277 Do not start Conky, but have it output the builtin default con‐
3278 fig file to ~/.config/conky/conky.conf for later customising.
3279
3281 ${sysconfdir}/conky/conky.conf
3282 Default system-wide configuration file. The value of
3283 ${sysconfdir} depends on the compile-time options (most likely
3284 /etc).
3285 ~/.config/conky/conky.conf
3287 Default personal configuration file.
3288
3290 Drawing to root or some other desktop window directly doesn't work with
3291 all window managers. Especially doesn't work well with Gnome and it has
3292 been reported that it doesn't work with KDE either. Nautilus can be
3293 disabled from drawing to desktop with program gconf-editor. Uncheck
3294 show_desktop in /apps/nautilus/preferences/. There is -w switch in
3295 Conky to set some specific window id. You might find xwininfo -tree
3296 useful to find the window to draw to. You can also use -o argument
3297 which makes Conky to create its own window. If you do try running Conky
3298 in its own window, be sure to read up on the own_window_type settings
3299 and experiment.
3300
3302 https://github.com/brndnmtthws/conky
3303 #conky on irc.freenode.net
3305
3307 Copyright (c) 2005-2019 Brenden Matthews, Philip Kovacs, et. al. Any
3308 original torsmo code is licensed under the BSD license (see LICENSE.BSD
3309 for a copy). All code written since the fork of torsmo is licensed un‐
3310 der the GPL (see LICENSE.GPL for a copy), except where noted different‐
3311 ly (such as in portmon and audacious code which are LGPL, and prss
3312 which is an MIT-style license).
3313
3315 The Conky dev team (see AUTHORS for a full list of contributors).
3316 2012-05-03 conky(1)