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 X_COORDINATE
167 X position.
168 -X | --display= DISPLAY
171 X11 display to use. Only available with build flag BUILD_X11 en‐
172 abled.
173 -y Y_COORDINATE
176 Y position.
177
180 Default configuration file location is ~/.config/conky/conky.conf or
181 ${sysconfdir}/conky/conky.conf. On most systems, sysconfdir is /etc,
182 and you can find the sample config file there in /etc/conky/conky.conf.
183 You might want to copy it to ~/.config/conky/conky.conf and then start
185 modifying it. Other configs can be found at https://github.com/brndnmt‐
186 thws/conky.
187 alignment
189 Aligned position on screen, may be top_left, top_right, top_mid‐
190 dle, bottom_left, bottom_right, bottom_middle, middle_left, mid‐
191 dle_middle, middle_right, or none (also can be abreviated as tl,
192 tr, tm, bl, br, bm, ml, mm, mr). See also gap_x and gap_y.
193 append_file
196 Append the file given as argument.
197 background
200 Boolean value, if true, Conky will be forked to background when
201 started.
202 border_inner_margin
205 Inner border margin in pixels (the margin between the border and
206 text).
207 border_outer_margin
210 Outer border margin in pixels (the margin between the border and
211 the edge of the window).
212 border_width
215 Border width in pixels.
216 colorN Predefine a color for use inside conky.text segments. Substi‐
219 tute N by a digit between 0 and 9, inclusively. When specifying
220 the color value in hex, omit the leading hash (#).
221 console_bar_fill
224 A character to fill the console bars. (default: '#')
225 console_bar_unfill
228 A character to unfill the console bars. (default: '.')
229 console_graph_ticks
232 A comma-separated list of strings to use as the bars of a graph
233 output to console/shell. The first list item is used for the
234 minimum bar height and the last item is used for the maximum,
235 e.g. " ,_,=,#".
236 cpu_avg_samples
239 The number of samples to average for CPU monitoring.
240 default_bar_height
243 Specify a default height for bars. If not specified, the default
244 value is 6.
245 default_bar_width
248 Specify a default width for bars. If not specified, the default
249 value is 0, which causes the bar to expand to fit the width of
250 your Conky window. If you set out_to_console = true, the default
251 value will be 10 for the text version of the bar.
252 default_color
255 Default color and border color.
256 default_gauge_height
259 Specify a default height for gauges. If not specified, the de‐
260 fault value is 25.
261 default_gauge_width
264 Specify a default width for gauges. If not specified, the de‐
265 fault value is 40.
266 default_graph_height
269 Specify a default height for graphs. If not specified, the de‐
270 fault value is 25.
271 default_graph_width
274 Specify a default width for graphs. If not specified, the de‐
275 fault value is 0, which causes the graph to expand to fit the
276 width of your Conky window. If you set out_to_console = true,
277 the text version of the graph will actually have no width and
278 you will need to set a sensible default or set the height and
279 width of each graph individually.
280 default_outline_color
283 Default outline color.
284 default_shade_color
287 Default shading color and border's shading color.
288 disable_auto_reload
291 Enable to disable the inotify-based auto config reload feature.
292 diskio_avg_samples
295 The number of samples to average for disk I/O monitoring.
296 display
299 Specify an X display to connect to.
300 xinerama_head
303 Specify a Xinerama head.
304 double_buffer
307 Use the Xdbe extension? (eliminates flicker) It is highly recom‐
308 mended to use own window with this one so double buffer won't be
309 so big.
310 draw_blended
313 Boolean, blend when rendering drawn image? Some images blend in‐
314 correctly breaking alpha with ARBG visuals. This provides a pos‐
315 sible work around by disabling blending. Defaults to true.
316 draw_borders
319 Draw borders around text.
320 draw_graph_borders
323 Draw borders around graphs.
324 draw_outline
327 Draw outlines.
328 draw_shades
331 Draw shades.
332 extra_newline
335 Put an extra newline at the end when writing to stdout, useful
336 for writing to awesome's wiboxes.
337 font Font name in X, xfontsel can be used to get a nice font.
340 fontN Predefine a font to be used in conky.text segments. Substitute
343 N by a number between 0 and 9 inclusive. Use the same format as
344 a font variable.
345 format_human_readable
348 If enabled, values which are in bytes will be printed in human
349 readable format (i.e., KiB, MiB, etc). If disabled, the number
350 of bytes is printed instead.
351 gap_x Gap, in pixels, between right or left border of screen, same as
354 passing -x at command line, e.g. gap_x 10. For other position
355 related stuff, see 'alignment'.
356 gap_y Gap, in pixels, between top or bottom border of screen, same as
359 passing -y at command line, e.g. gap_y 10. For other position
360 related stuff, see 'alignment'.
361 github_token
364 Specify API token for GitHub notifications.
365 https://github.com/settings/tokens/new?scopes=notifications&de‐
367 scription=conky
368 hddtemp_host
371 Hostname to connect to for hddtemp objects. Defaults to
372 "127.0.0.1".
373 hddtemp_port
376 Port to use for hddtemp connections. Defaults to 7634.
377 http_refresh
380 When this is set the page generated with out_to_http will auto‐
381 matically refresh each interval. Default value is no.
382 if_up_strictness
385 How strict should if_up be when testing an interface for being
386 up? The value is one of up, link or address, to check for the
387 interface being solely up, being up and having link or being up,
388 having link and an assigned IP address.
389 imap Default global IMAP server. Arguments are: "host user pass [-i
392 interval (in seconds)] [-f 'folder'] [-p port] [-e 'command']
393 [-r retries]". Default port is 143, default folder is 'INBOX',
394 default interval is 5 minutes, and default number of retries be‐
395 fore giving up is 5. If the password is supplied as '*', you
396 will be prompted to enter the password when Conky starts.
397 imlib_cache_flush_interval
400 Interval (in seconds) to flush Imlib2 cache.
401 imlib_cache_size
404 Imlib2 image cache size, in bytes. Defaults to 4MiB. Increase
405 this value if you use $image lots. Set to 0 to disable the image
406 cache.
407 lua_draw_hook_post function_name [function arguments]
410 This function, if defined, will be called by Conky through each
411 iteration after drawing to the window. Requires X support. Takes
412 any number of optional arguments. Use this hook for drawing
413 things on top of what Conky draws. Conky puts 'conky_' in front
414 of function_name to prevent accidental calls to the wrong func‐
415 tion unless you place 'conky_' in front of it yourself.
416 lua_draw_hook_pre function_name [function arguments]
419 This function, if defined, will be called by Conky through each
420 iteration before drawing to the window. Requires X support.
421 Takes any number of optional arguments. Use this hook for draw‐
422 ing things on top of what Conky draws. Conky puts 'conky_' in
423 front of function_name to prevent accidental calls to the wrong
424 function unless you place 'conky_' in front of it yourself.
425 lua_load
428 Loads the Lua scripts separated by spaces.
429 lua_shutdown_hook function_name [function arguments]
432 This function, if defined, will be called by Conky at shutdown
433 or when the configuration is reloaded. Use this hook to clean up
434 after yourself, such as freeing memory which has been allocated
435 by external libraries via Lua. Conky puts 'conky_' in front of
436 function_name to prevent accidental calls to the wrong function
437 unless you place 'conky_' in front of it yourself.
438 lua_startup_hook function_name [function arguments]
441 This function, if defined, will be called by Conky at startup or
442 when the configuration is reloaded. Use this hook to initialize
443 values, or for any run-once applications. Conky puts 'conky_' in
444 front of function_name to prevent accidental calls to the wrong
445 function unless you place 'conky_' in front of it yourself.
446 mail_spool
449 Mail spool for mail checking.
450 max_port_monitor_connections
453 Allow each port monitor to track at most this many connections
454 (if 0 or not set, default is 256).
455 max_text_width width
458 When a line in the output contains 'width' chars and the end
459 isn't reached, the next char will start on a new line. If you
460 want to make sure that lines don't get broken, set 'width' to 0.
461 max_user_text bytes
464 Maximum size of user text buffer, i.e. text inside conky.text
465 section in config file (default is 16384 bytes).
466 maximum_width pixels
469 Maximum width of window.
470 minimum_height height
473 Minimum height of the window.
474 minimum_width width
477 Minimum width of window.
478 mpd_host
481 Host of MPD server.
482 mpd_password
485 MPD server password.
486 mpd_port
489 Port of MPD server.
490 mysql_host
493 Host of MySQL server. Defaults to localhost.
494 mysql_port
497 Port of MySQL server. Defaults to the default mysql port.
498 mysql_user
501 MySQL user name to use when connecting to the server. Defaults
502 to your username.
503 mysql_password
506 Password of the MySQL user. Place it between "-chars. When this
507 is not set there is no password used.
508 mysql_db
511 MySQL database to use. Defaults to mysql.
512 music_player_interval
515 Music player thread update interval (defaults to Conky's update
516 interval).
517 net_avg_samples
520 The number of samples to average for net data.
521 no_buffers
524 Subtract (file system) buffers from used memory.
525 nvidia_display
528 The display that the nvidia variable will use (defaults to the
529 value of the display variable).
530 out_to_console
533 Print text to stdout.
534 out_to_http
537 Let conky act as a small http-server serving its text.
538 out_to_ncurses
541 Print text in the console, but use ncurses so that conky can
542 print the text of a new update over the old text. (In the future
543 this will provide more useful things).
544 out_to_stderr
547 Print text to stderr.
548 out_to_x
551 When set to no, there will be no output in X (useful when you
552 also use things like out_to_console). If you set it to no, make
553 sure that it's placed before all other X-related setting (take
554 the first line of your configfile to be sure). Default value is
555 yes.
556 override_utf8_locale
559 Force UTF8. Requires XFT.
560 overwrite_file
563 Overwrite the file given as argument.
564 own_window
567 Boolean, create own window to draw.
568 own_window_class
571 Manually set the WM_CLASS name. Defaults to "Conky".
572 own_window_colour colour
575 If own_window_transparent no, set a specified background colour
576 (defaults to black). Takes either a hex value (e.g. '#ffffff'),
577 a shorthand hex value (e.g. '#fff'), or a valid RGB name (see
578 /usr/lib/X11/rgb.txt).
579 own_window_hints undecorated,below,above,sticky,skip_taskbar,skip_pager
582 If own_window is yes, you may use these window manager hints to
583 affect the way Conky displays. Notes: Use own_window_type desk‐
584 top as another way to implement many of these hints implicitly.
585 If you use own_window_type override, window manager hints have
586 no meaning and are ignored.
587 own_window_title
590 Manually set the window name. Defaults to "conky (<hostname>)".
591 own_window_argb_visual
594 Boolean, use ARGB visual? ARGB can be used for real transparen‐
595 cy, note that a composite manager is required for real trans‐
596 parency. This option will not work as desired (in most cases) in
597 conjunction with 'own_window_type override'.
598 own_window_argb_value
601 When ARGB visuals are enabled, this use this to modify the alpha
602 value used. Valid range is 0-255, where 0 is 0% opacity, and 255
603 is 100% opacity.
604 own_window_transparent
607 Boolean, set transparency? If ARGB visual is enabled, sets back‐
608 ground opacity to 0%.
609 own_window_type
612 if own_window is yes, you may specify type normal, desktop,
613 dock, panel or override (default: normal). Desktop windows are
614 special windows that have no window decorations; are always vis‐
615 ible on your desktop; do not appear in your pager or taskbar;
616 and are sticky across all workspaces. Panel windows reserve
617 space along a desktop edge, just like panels and taskbars, pre‐
618 venting maximized windows from overlapping them. The edge is
619 chosen based on the alignment option. Override windows are not
620 under the control of the window manager. Hints are ignored.
621 This type of window can be useful for certain situations.
622 pad_percents
625 Pad percentages to this many decimals (0 = no padding).
626 pop3 Default global POP3 server. Arguments are: "host user pass [-i
629 interval (in seconds)] [-p port] [-e 'command'] [-r retries]".
630 Default port is 110, default interval is 5 minutes, and default
631 number of retries before giving up is 5. If the password is sup‐
632 plied as '*', you will be prompted to enter the password when
633 Conky starts.
634 short_units
637 Shortens units to a single character (kiB->k, GiB->G, etc.). De‐
638 fault is off.
639 show_graph_range
642 Shows the time range covered by a graph.
643 show_graph_scale
646 Shows the maximum value in scaled graphs.
647 stippled_borders
650 Border stippling (dashing) in pixels.
651 temperature_unit
654 Desired output unit of all objects displaying a temperature.
655 Parameters are either "fahrenheit" or "celsius". The default
656 unit is degree Celsius.
657 templateN
660 Define a template for later use inside conky.text segments.
661 Substitute N by a digit between 0 and 9, inclusively. The value
662 of the variable is being inserted into the stuff inside
663 conky.text at the corresponding position, but before some sub‐
664 stitutions are applied:
665 '\n' -> newline
667 '\\' -> backslash
668 '\ ' -> space
669 '\N' -> template argument N (starting from 1)
670 text_buffer_size bytes
673 Size of the standard text buffer (default is 256 bytes). This
674 buffer is used for intermediary text, such as individual lines,
675 output from $exec vars, and various other variables. Increasing
676 the size of this buffer can drastically reduce Conky's perfor‐
677 mance, but will allow for more text display per variable. The
678 size of this buffer cannot be smaller than the default value of
679 256 bytes.
680 times_in_seconds
683 If true, variables that output times output a number that repre‐
684 sents seconds. This doesn't affect $time, $tztime and $utime.
685 top_cpu_separate
688 If true, cpu in top will show usage of one processor's power. If
689 false, cpu in top will show the usage of all processors' power
690 combined.
691 top_name_verbose
694 If true, top name shows the full command line of each process,
695 including arguments (whenever possible). Otherwise, only the
696 basename is displayed. Default value is false.
697 top_name_width
700 Width for $top name value (defaults to 15 characters).
701 total_run_times
704 Total number of times for Conky to update before quitting. Zero
705 makes Conky run forever.
706 update_interval seconds
709 Update interval.
710 update_interval_on_battery seconds
713 Update interval when running on battery power.
714 detect_battery
717 One or more batteries to check in order to use update_inter‐
718 val_on_battery (comma separated, BAT0 default).
719 uppercase
722 Boolean value, if true, text is rendered in upper case.
723 use_spacer
726 Adds spaces around certain objects to stop them from moving oth‐
727 er things around. Arguments are left, right, and none (default).
728 The old true/false values are deprecated and default to
729 right/none respectively. Note that this only helps if you are
730 using a mono font, such as Bitstream Vera Sans Mono.
731 use_xft
734 Use Xft (anti-aliased font and stuff).
735 xftalpha
738 Alpha of Xft font. Must be a value at or between 1 and 0.
739
742 Colours are parsed using XParsecolor(), there might be a list of them:
743 /usr/share/X11/rgb.txt. Colour can be also in #rrggbb format (hex).
744 Some objects may create threads, and sometimes these threads will not
746 be destroyed until Conky terminates. There is no way to destroy or
747 clean up threads while Conky is running. For example, if you use an MPD
748 variable, the MPD thread will keep running until Conky dies. Some
749 threaded objects will use one of the parameters as a 'key', so that you
750 only have 1 relevant thread running (for example, the $curl, $rss and
751 $weather objects launch one thread per URI).
752 acpiacadapter (adapter)
754 ACPI ac adapter state. On linux, the adapter option specifies
755 the subfolder of /sys/class/power_supply containing the state
756 information (tries "AC" and "ADP1" if there is no argument giv‐
757 en). Non-linux systems ignore it.
758 acpifan
761 ACPI fan state.
762 acpitemp
765 ACPI temperature in C.
766 addr (interface)
769 IP address for an interface, or "No Address" if no address is
770 assigned.
771 addrs (interface)
774 IP addresses for an interface (if one - works like addr). Linux
775 only.
776 adt746xcpu
779 CPU temperature from therm_adt746x.
780 adt746xfan
783 Fan speed from therm_adt746x.
784 alignc (num)
787 Align text to centre.
788 alignr (num)
791 Right-justify text, with space of N.
792 apcupsd host port
795 Sets up the connection to apcupsd daemon. Prints nothing, de‐
796 faults to localhost:3551.
797 apcupsd_cable
800 Prints the UPS connection type.
801 apcupsd_charge
804 Current battery capacity in percent.
805 apcupsd_lastxfer
808 Reason for last transfer from line to battery.
809 apcupsd_linev
812 Nominal input voltage.
813 apcupsd_load
816 Current load in percent.
817 apcupsd_loadbar
820 Bar showing current load.
821 apcupsd_loadgauge (height),(width)
824 Gauge that shows current load.
825 apcupsd_loadgraph (height),(width) (gradient colour 1) (gradient colour
828 2) (scale) (-t) (-l)
829 History graph of current load.
830 apcupsd_model
833 Prints the model of the UPS.
834 apcupsd_name
837 Prints the UPS user-defined name.
838 apcupsd_status
841 Prints current status (on-line, on-battery).
842 apcupsd_temp
845 Current internal temperature.
846 apcupsd_timeleft
849 Time left to run on battery.
850 apcupsd_upsmode
853 Prints the UPS mode (e.g. standalone).
854 apm_adapter
857 Display APM AC adapter status. FreeBSD, OpenBSD only.
858 apm_battery_life
861 Display APM battery life in percent. FreeBSD, OpenBSD only.
862 apm_battery_time
865 Display remaining APM battery life in hh:mm:ss or "unknown" if
866 AC adapterstatus is on-line or charging. FreeBSD, OpenBSD only.
867 audacious_bar (height),(width)
870 Progress bar.
871 audacious_bitrate
874 Bitrate of current tune.
875 audacious_channels
878 Number of audio channels of current tune.
879 audacious_filename
882 Full path and filename of current tune.
883 audacious_frequency
886 Sampling frequency of current tune.
887 audacious_length
890 Total length of current tune as MM:SS.
891 audacious_length_seconds
894 Total length of current tune in seconds.
895 audacious_main_volume
898 The current volume fetched from Audacious.
899 audacious_playlist_length
902 Number of tunes in playlist.
903 audacious_playlist_position
906 Playlist position of current tune.
907 audacious_position
910 Position of current tune (MM:SS).
911 audacious_position_seconds
914 Position of current tune in seconds.
915 audacious_status
918 Player status (Playing/Paused/Stopped/Not running).
919 audacious_title (max length)
922 Title of current tune with optional maximum length specifier.
923 battery (num)
926 Battery status and remaining percentage capacity of ACPI or APM
927 battery. ACPI battery number can be given as argument (default
928 is BAT0).
929 battery_bar (height),(width) (num)
932 Battery percentage remaining of ACPI battery in a bar. ACPI bat‐
933 tery number can be given as argument (default is BAT0, use all
934 to get the mean percentage remaining for all batteries).
935 battery_percent (num)
938 Battery percentage remaining for ACPI battery. ACPI battery num‐
939 ber can be given as argument (default is BAT0, use all to get
940 the mean percentage remaining for all batteries).
941 battery_short (num)
944 Battery status and remaining percentage capacity of ACPI or APM
945 battery. ACPI battery number can be given as argument (default
946 is BAT0). This mode display a short status, which means that C
947 is displayed instead of charging, D for discharging, F for full,
948 N for not present, E for empty and U for unknown.
949 battery_status (num)
952 Battery status for ACPI battery. ACPI battery number can be giv‐
953 en as argument (default is BAT0).
954 battery_time (num)
957 Battery charge/discharge time remaining of ACPI battery. ACPI
958 battery number can be given as argument (default is BAT0).
959 blink text_and_other_conky_vars
962 Let 'text_and_other_conky_vars' blink on and off.
963 buffers
966 Amount of memory buffered.
967 cached Amount of memory cached.
970 cat file
973 Reads a file and displays the contents in conky. This is useful
974 if you have an independent process generating output that you
975 want to include in conky.
976 catp file
979 Reads a file and displays the contents in conky. This is useful
980 if you have an independent process generating output that you
981 want to include in conky. This differs from $cat in that it
982 parses the contents of the file, so you can insert things like
983 ${color red}hi!${color} in your file and have it correctly
984 parsed by Conky.
985 cmdline_to_pid string
988 PID of the first process that has string in its commandline.
989 cmus_aaa
992 Print aaa status of cmus (all/artist/album).
993 cmus_album
996 Prints the album of the current cmus song.
997 cmus_artist
1000 Prints the artist of the current cmus song.
1001 cmus_curtime
1004 Current time of the current cmus song.
1005 cmus_file
1008 Print the file name of the current cmus song.
1009 cmus_date
1012 Print the date of the current cmus song.
1013 cmus_genre
1016 Print the genre name of the current cmus song.
1017 cmus_percent
1020 Percent of song's progress.
1021 cmus_progress (height),(width)
1024 cmus' progress bar.
1025 cmus_random
1028 Random status of cmus (on/off).
1029 cmus_repeat
1032 Repeat status of cmus (song/all/off).
1033 cmus_state
1036 Current state of cmus (playing, paused, stopped etc).
1037 cmus_timeleft
1040 Time left of the current cmus song.
1041 cmus_title
1044 Prints the title of the current cmus song.
1045 cmus_totaltime
1048 Total length of the current cmus song.
1049 cmus_track
1052 Print track number of current cmus song.
1053 color (color)
1056 Change drawing color to 'color' which is a name of a color or a
1057 hexcode preceded with #, e.g. #0A1B2C. If you use ncurses only
1058 the following colors are supported: red, green, yellow, blue,
1059 magenta, cyan, black, and white.
1060 colorN Change drawing color to colorN configuration option, where N is
1063 a digit between 0 and 9, inclusively.
1064 combine var1 var2
1067 Places the lines of var2 to the right of the lines of var1 sepa‐
1068 rated by the chars that are put between var1 and var2. For exam‐
1069 ple: ${combine ${head /proc/cpuinfo 2} - ${head /proc/meminfo
1070 1}} gives as output "cpuinfo_line1 - meminfo_line1" on line 1
1071 and "cpuinfo_line2 -" on line 2. $combine vars can also be nest‐
1072 ed to place more vars next to each other.
1073 conky_build_arch
1076 CPU architecture Conky was built for.
1077 conky_build_date
1080 Date Conky was built.
1081 conky_version
1084 Conky version.
1085 cpu (cpuN)
1088 CPU usage in percents. For SMP machines, the CPU number can be
1089 provided as an argument. ${cpu cpu0} is the total usage, and
1090 ${cpu cpuX} (X >= 1) are individual CPUs.
1091 cpubar (cpuN) (height),(width)
1094 Bar that shows CPU usage, height is bar's height in pixels. See
1095 $cpu for more info on SMP.
1096 cpugauge (cpuN) (height),(width)
1099 Elliptical gauge that shows CPU usage, height and width are
1100 gauge's vertical and horizontal axis respectively. See $cpu for
1101 more info on SMP.
1102 cpugraph (cpuN) (height),(width) (gradient colour 1) (gradient colour
1105 2) (scale) (-t) (-l)
1106 CPU usage graph, with optional colours in hex, minus the #. See
1107 $cpu for more info on SMP. Uses a logarithmic scale (to see
1108 small numbers) when you use the -l switch. Takes the switch '-t'
1109 to use a temperature gradient, which makes the gradient values
1110 change depending on the amplitude of a particular graph value
1111 (try it and see).
1112 curl url (interval_in_minutes)
1115 Download data from URI using Curl at the specified interval.
1116 The interval may be a positive floating point value (0 is al‐
1117 lowed), otherwise defaults to 15 minutes. Most useful when used
1118 in conjunction with Lua and the Lua API. This object is thread‐
1119 ed, and once a thread is created it can't be explicitly de‐
1120 stroyed. One thread will run for each URI specified. You can use
1121 any protocol that Curl supports.
1122 desktop
1125 Number of the desktop on which conky is running or the message
1126 "Not running in X" if this is the case.
1127 desktop_name
1130 Name of the desktop on which conky is running or the message
1131 "Not running in X" if this is the case.
1132 desktop_number
1135 Number of desktops or the message "Not running in X" if this is
1136 the case.
1137 disk_protect device
1140 Disk protection status, if supported (needs kernel-patch).
1141 Prints either "frozen" or "free " (note the padding).
1142 diskio (device)
1145 Displays current disk IO. Device is optional, and takes the form
1146 of sda for /dev/sda. A block device label can be specified with
1147 label:foo and a block device partuuid can be specified with par‐
1148 tuuid:40000000-01.
1149 diskio_read (device)
1152 Displays current disk IO for reads. Device as in diskio.
1153 diskio_write (device)
1156 Displays current disk IO for writes. Device as in diskio.
1157 diskiograph (device) (height),(width) (gradient colour 1) (gradient
1160 colour 2) (scale) (-t) (-l)
1161 Disk IO graph, colours defined in hex, minus the #. If scale is
1162 non-zero, it becomes the scale for the graph. Uses a logarithmic
1163 scale (to see small numbers) when you use -l switch. Takes the
1164 switch '-t' to use a temperature gradient, which makes the gra‐
1165 dient values change depending on the amplitude of a particular
1166 graph value (try it and see).
1167 diskiograph_read (device) (height),(width) (gradient colour 1) (gradi‐
1170 ent colour 2) (scale) (-t) (-l)
1171 Disk IO graph for reads, colours defined in hex, minus the #. If
1172 scale is non-zero, it becomes the scale for the graph. Device as
1173 in diskio. Uses a logarithmic scale (to see small numbers) when
1174 you use -l switch. Takes the switch '-t' to use a temperature
1175 gradient, which makes the gradient values change depending on
1176 the amplitude of a particular graph value (try it and see).
1177 diskiograph_write (device) (height),(width) (gradient colour 1) (gradi‐
1180 ent colour 2) (scale) (-t) (-l)
1181 Disk IO graph for writes, colours defined in hex, minus the #.
1182 If scale is non-zero, it becomes the scale for the graph. Device
1183 as in diskio. Uses a logarithmic scale (to see small numbers)
1184 when you use -l switch. Takes the switch '-t' to use a tempera‐
1185 ture gradient, which makes the gradient values change depending
1186 on the amplitude of a particular graph value (try it and see).
1187 distribution
1190 The name of the distribution. It could be that some of the
1191 untested distributions will show up wrong or as "unknown", if
1192 that's the case post a bug on sourceforge, make sure it contains
1193 the name of your distribution, the contents of /proc/version and
1194 if there is a file that only exists on your distribution, also
1195 add the path of that file in the bug. If there is no such file,
1196 please add another way which we can use to identify your distri‐
1197 bution.
1198 downspeed (net)
1201 Download speed in suitable IEC units.
1202 downspeedf (net)
1205 Download speed in KiB with one decimal.
1206 downspeedgraph (netdev) (height),(width) (gradient colour 1) (gradient
1209 colour 2) (scale) (-t) (-l)
1210 Download speed graph, colours defined in hex, minus the #. If
1211 scale is non-zero, it becomes the scale for the graph. Uses a
1212 logarithmic scale (to see small numbers) when you use -l switch.
1213 Takes the switch '-t' to use a temperature gradient, which makes
1214 the gradient values change depending on the amplitude of a par‐
1215 ticular graph value (try it and see).
1216 draft_mails (maildir) (interval)
1219 Number of mails marked as draft in the specified mailbox or mail
1220 spool if not. Only maildir type mailboxes are supported, mbox
1221 type will return -1.
1222 else Text to show if any of the above are not true.
1225 endif Ends an $if block.
1228 entropy_avail
1231 Current entropy available for crypto freaks.
1232 entropy_bar (height),(width)
1235 Normalized bar of available entropy for crypto freaks.
1236 entropy_perc
1239 Percentage of entropy available in comparison to the poolsize.
1240 entropy_poolsize
1243 Total size of system entropy pool for crypto freaks.
1244 eval string
1247 Evaluates given string according to the rules of conky.text in‐
1248 terpretation, i.e. parsing any contained text object specifica‐
1249 tions into their output, any occuring '$$' into a single '$' and
1250 so on. The output is then being parsed again.
1251 exec command
1254 Executes a shell command and displays the output in conky.
1255 Warning: this takes a lot more resources than other variables.
1256 I'd recommend coding wanted behaviour in C/C++ and posting a
1257 patch.
1258 execbar (height),(width) command
1261 Same as exec, except if the first value returned is a value be‐
1262 tween 0-100, it will use that number to draw a horizontal bar.
1263 The height and width parameters are optional, and default to the
1264 default_bar_height and default_bar_width config settings, re‐
1265 spectively.
1266 execgauge (height),(width) command
1269 Same as exec, except if the first value returned is a value be‐
1270 tween 0-100, it will use that number to draw a round gauge (much
1271 like a vehicle speedometer). The height and width parameters are
1272 optional, and default to the default_gauge_height and de‐
1273 fault_gauge_width config settings, respectively.
1274 execgraph command (height),(width) (gradient color 1) (gradient color
1277 2) (scale) (-t) (-l)
1278 Draws a horizontally scrolling graph with values from 0-100
1279 plotted on the vertical axis. All parameters following the com‐
1280 mand are optional. Gradient colors can be specified as hexadeci‐
1281 mal values with no 0x or # prefix. Use the -t switch to enable a
1282 temperature gradient, so that small values are "cold" with color
1283 1 and large values are "hot" with color 2. Without the -t
1284 switch, the colors produce a horizontal gradient spanning the
1285 width of the graph. The scale parameter defines the maximum val‐
1286 ue of the graph. Use the -l switch to enable a logarithmic
1287 scale, which helps to see small values. The default size for
1288 graphs can be controlled via the default_graph_height and de‐
1289 fault_graph_width config settings.
1290 If you need to execute a command with spaces, you have a couple
1292 options: 1) wrap your command in double-quotes, or 2) put your
1293 command into a separate file, such as ~/bin/myscript.sh, and use
1294 that as your execgraph command. Remember to make your script ex‐
1295 ecutable!
1296 In the following example, we set up execgraph to display seconds
1298 (0-59) on a graph that is 50px high and 200px wide, using a tem‐
1299 perature gradient with colors ranging from red for small values
1300 (FF0000) to yellow for large values (FFFF00). We set the scale
1301 to 60.
1302 ${execgraph ~/seconds.sh 50,200 FF0000 FFFF00 60 -t}
1304 execi interval command
1306 Same as exec, but with a specific interval in seconds. The in‐
1307 terval can't be less than the update_interval in your configura‐
1308 tion. See also $texeci.
1309 execibar interval (height),(width) command
1312 Same as execbar, but with an interval.
1313 execigauge interval (height),(width) command
1316 Same as execgauge, but with an interval.
1317 execigraph interval command (height),(width) (gradient color 1) (gradi‐
1320 ent color 2) (scale) (-t) (-l)
1321 Same as execgraph, but with an interval.
1322 execp command
1325 Executes a shell command and displays the output in conky.
1326 Warning: this takes a lot more resources than other variables.
1327 I'd recommend coding wanted behaviour in C/C++ and posting a
1328 patch. This differs from $exec in that it parses the output of
1329 the command, so you can insert things like ${color red}hi!${col‐
1330 or} in your script and have it correctly parsed by Conky.
1331 Caveats: Conky parses and evaluates the output of $execp every
1332 time Conky loops, and then destroys all the objects. If you try
1333 to use anything like $execi within an $execp statement, it will
1334 functionally run at the same interval that the $execp statement
1335 runs, as it is created and destroyed at every interval.
1336 execpi interval command
1339 Same as execp, but with an interval. Note that the output from
1340 the $execpi command is still parsed and evaluated at every in‐
1341 terval.
1342 flagged_mails (maildir) (interval)
1345 Number of mails marked as flagged in the specified mailbox or
1346 mail spool if not. Only maildir type mailboxes are supported,
1347 mbox type will return -1.
1348 font (font)
1351 Specify a different font. This new font will apply to the cur‐
1352 rent line and everything following. You can use a $font with no
1353 arguments to change back to the default font (much like with
1354 $color).
1355 fontN Change font to fontN configuration option, where N is a digit
1358 between 0 and 9, inclusively.
1359 format_time seconds format
1362 Format time given in seconds. This var only works when the
1363 times_in_seconds configuration setting is on. Format is a string
1364 that should start and end with a "-char. The "-chars are not
1365 part of the output, \w,\d,\h,\m,\s,\(,\) and \\ are replaced by
1366 weeks,days,hours,minutes,seconds,(,) and \. If you leave out a
1367 unit, it's value will be expressed in the highest unite lower
1368 then the one left out. Text between ()-chars will not be visible
1369 if a replaced unit in this text is 0. If seconds is a decimal
1370 number then you can see the numbers behind the point by using \S
1371 followed by a number that specifies the amount of digits behind
1372 the point that you want to see (maximum 9). You can also place a
1373 'x' behind \S so you have all digits behind the point and no
1374 trailing zero's. (also maximum 9).
1375 forwarded_mails (maildir) (interval)
1378 Number of mails marked as forwarded in the specified mailbox or
1379 mail spool if not. Only maildir type mailboxes are supported,
1380 mbox type will return -1.
1381 freq (n)
1384 Returns CPU #n's frequency in MHz. CPUs are counted from 1. If
1385 omitted, the parameter defaults to 1.
1386 freq_g (n)
1389 Returns CPU #n's frequency in GHz. CPUs are counted from 1. If
1390 omitted, the parameter defaults to 1.
1391 freq2 (n)
1394 Returns CPU #n's clock speed from assembly in MHz. CPUs are
1395 counted from 1. If omitted, the parameter defaults to 1.
1396 fs_bar (height),(width) fs
1399 Bar that shows how much space is used on a file system. height
1400 is the height in pixels. fs is any file on that file system.
1401 fs_bar_free (height),(width) fs
1404 Bar that shows how much space is free on a file system. height
1405 is the height in pixels. fs is any file on that file system.
1406 fs_free (fs)
1409 Free space on a file system available for users.
1410 fs_free_perc (fs)
1413 Free percentage of space on a file system available for users.
1414 fs_size (fs)
1417 File system size.
1418 fs_type (fs)
1421 File system type.
1422 fs_used (fs)
1425 File system used space.
1426 fs_used_perc (fs)
1429 Percent of file system used space.
1430 github_notifications
1433 Number of GitHub notifications.
1434 goto x The next element will be printed at position 'x'.
1437 gw_iface
1440 Displays the default route's interface or "multiple"/"none" ac‐
1441 cordingly.
1442 gw_ip Displays the default gateway's IP or "multiple"/"none" accord‐
1445 ingly.
1446 hddtemp (dev)
1449 Displays temperature of a selected hard disk drive as reported
1450 by the hddtemp daemon. Use hddtemp_host and hddtemp_port to
1451 specify a host and port for all hddtemp objects. If no dev pa‐
1452 rameter is given, the first disk returned by the hddtemp daemon
1453 is used.
1454 head logfile lines (next_check)
1457 Displays first N lines of supplied text file. The file is
1458 checked every 'next_check' update. If next_check is not sup‐
1459 plied, Conky defaults to 2. Max of 30 lines can be displayed, or
1460 until the text buffer is filled.
1461 hr (height)
1464 Horizontal line, height is the height in pixels.
1465 hwmon (dev) type n (factor offset)
1468 Hwmon sensor from sysfs (Linux 2.6). Parameter dev can be: 1)
1469 Number. e.g '1' means hwmon1. 2) Module name. e.g. 'k10temp'
1470 means the first hwmon device whose module name is 'k10temp. 3)
1471 Omitted. Then the first hwmon device (hwmon0) will be used. Pa‐
1472 rameter type is either 'in' or 'vol' meaning voltage; 'fan'
1473 meaning fan; 'temp' meaning temperature. Parameter n is number
1474 of the sensor. See /sys/class/hwmon/ on your local computer.
1475 The optional arguments 'factor' and 'offset' allow precalcula‐
1476 tion of the raw input, which is being modified as follows: 'in‐
1477 put = input * factor + offset'. Note that they have to be given
1478 as decimal values (i.e. contain at least one decimal place).
1479 iface (number)
1482 Display interface names starting from 1, eg ${iface 1}.
1483 i2c (dev) type n (factor offset)
1486 I2C sensor from sysfs (Linux 2.6). Parameter dev may be omitted
1487 if you have only one I2C device. Parameter type is either 'in'
1488 or 'vol' meaning voltage; 'fan' meaning fan; 'temp' meaning tem‐
1489 perature. Parameter n is number of the sensor. See
1490 /sys/bus/i2c/devices/ on your local computer. The optional argu‐
1491 ments 'factor' and 'offset' allow precalculation of the raw in‐
1492 put, which is being modified as follows: 'input = input * factor
1493 + offset'. Note that they have to be given as decimal values
1494 (i.e. contain at least one decimal place).
1495 i8k_ac_status
1498 If running the i8k kernel driver for Inspiron laptops, displays
1499 whether ac power is on, as listed in /proc/i8k (translated to
1500 human-readable). Beware that this is by default not enabled by
1501 i8k itself.
1502 i8k_bios
1505 If running the i8k kernel driver for Inspiron laptops, displays
1506 the bios version as listed in /proc/i8k.
1507 i8k_buttons_status
1510 If running the i8k kernel driver for Inspiron laptops, displays
1511 the volume buttons status as listed in /proc/i8k.
1512 i8k_cpu_temp
1515 If running the i8k kernel driver for Inspiron laptops, displays
1516 the cpu temperature in Celsius, as reported by /proc/i8k.
1517 i8k_left_fan_rpm
1520 If running the i8k kernel driver for Inspiron laptops, displays
1521 the left fan's rate of rotation, in revolutions per minute as
1522 listed in /proc/i8k. Beware, some laptops i8k reports these fans
1523 in reverse order.
1524 i8k_left_fan_status
1527 If running the i8k kernel driver for Inspiron laptops, displays
1528 the left fan status as listed in /proc/i8k (translated to human-
1529 readable). Beware, some laptops i8k reports these fans in re‐
1530 verse order.
1531 i8k_right_fan_rpm
1534 If running the i8k kernel driver for Inspiron laptops, displays
1535 the right fan's rate of rotation, in revolutions per minute as
1536 listed in /proc/i8k. Beware, some laptops i8k reports these fans
1537 in reverse order.
1538 i8k_right_fan_status
1541 If running the i8k kernel driver for Inspiron laptops, displays
1542 the right fan status as listed in /proc/i8k (translated to hu‐
1543 man-readable). Beware, some laptops i8k reports these fans in
1544 reverse order.
1545 i8k_serial
1548 If running the i8k kernel driver for Inspiron laptops, displays
1549 your laptop serial number as listed in /proc/i8k.
1550 i8k_version
1553 If running the i8k kernel driver for Inspiron laptops, displays
1554 the version formatting of /proc/i8k.
1555 ibm_brightness
1558 If running the IBM ACPI, displays the brigtness of the laptops's
1559 LCD (0-7).
1560 ibm_fan
1563 If running the IBM ACPI, displays the fan speed.
1564 ibm_temps N
1567 If running the IBM ACPI, displays the temperatures from the IBM
1568 temperature sensors (N=0..7) Sensor 0 is on the CPU, 3 is on the
1569 GPU.
1570 ibm_thinklight
1573 If running the IBM ACPI, displays the status of your Think‐
1574 Light™. Value is either 'on', 'off' or 'unknown'.
1575 ibm_volume
1578 If running the IBM ACPI, displays the "master" volume, con‐
1579 trolled by the volume keys (0-14).
1580 ical number file
1583 Shows title of event number 'number' in the ical (RFC 5545) file
1584 'file'. The events are first ordered by starting time, events
1585 that started in the past are ignored. The events that are shown
1586 are the VEVENTS, the title that is shown is the SUMMARY and the
1587 starting time used for sorting is DTSTART.
1588 irc server(:port) #channel (max_msg_lines)
1591 Shows everything that's being told in #channel on IRCserver
1592 'server'. TCP-port 6667 is used for the connection unless 'port'
1593 is specified. Shows everything since the last time or the last
1594 'max_msg_lines' entries if specified.
1595 iconv_start codeset_from codeset_to
1598 Convert text from one codeset to another using GNU iconv. Needs
1599 to be stopped with iconv_stop.
1600 iconv_stop
1603 Stop iconv codeset conversion.
1604 if_empty (var)
1607 if conky variable VAR is empty, display everything between
1608 $if_empty and the matching $endif.
1609 if_existing file (string)
1612 if FILE exists, display everything between if_existing and the
1613 matching $endif. The optional second parameter checks for FILE
1614 containing the specified string and prints everything between
1615 $if_existing and the matching $endif.
1616 if_gw if there is at least one default gateway, display everything be‐
1619 tween $if_gw and the matching $endif.
1620 if_match expression
1623 Evaluates the given boolean expression, printing everything be‐
1624 tween $if_match and the matching $endif depending on whether the
1625 evaluation returns true or not. Valid expressions consist of a
1626 left side, an operator and a right side. Left and right sides
1627 are being parsed for contained text objects before evaluation.
1628 Recognised left and right side types are:
1629 doubleArgument consists of only digits and a single dot.
1631 longArgument consists of only digits.
1632 stringArgument is enclosed in quotation marks. (")
1633 Valid operands are: '>', '<', '>=', '<=', '==', '!='.
1635 if_mixer_mute (mixer)
1638 If mixer exists, display everything between $if_mixer_mute and
1639 the matching $endif. If no mixer is specified, "Vol" is used.
1640 if_mounted (mountpoint)
1643 if MOUNTPOINT is mounted, display everything between $if_mounted
1644 and the matching $endif.
1645 if_mpd_playing
1648 if mpd is playing or paused, display everything between
1649 $if_mpd_playing and the matching $endif.
1650 if_pa_sink_muted
1653 If Pulseaudio's default sink is muted, display everything be‐
1654 tween $if_pa_sink_muted and the corresponding $else or $endif.
1655 if_running (process)
1658 If PROCESS is running, display everything between $if_running
1659 and the corresponding $else or $endif. Note that PROCESS may be
1660 either a full command line with arguments (without the directory
1661 prefix), or simply the name of an executable. For example, ei‐
1662 ther of the following will be true if there is a running process
1663 with the command line /usr/bin/conky -u 5:
1664 ${if_running conky -u 5}or ${if_running conky}
1666 It is important not to include trailing spaces. For example,
1668 ${if_running conky }will be false.
1669 if_smapi_bat_installed (INDEX)
1672 when using smapi, if the battery with index INDEX is installed,
1673 display everything between $if_smapi_bat_installed and the
1674 matching $endif.
1675 if_up (interface)
1678 if INTERFACE exists and is up, display everything between $if_up
1679 and the matching $endif.
1680 if_updatenr (updatenr)
1683 If it's the UPDATENR-th time that conky updates, display every‐
1684 thing between $if_updatenr and the matching $endif. The counter
1685 resets when the highest UPDATENR is reached. Example : "{$if_up‐
1686 datenr 1}foo$endif{$if_updatenr 2}bar$endif{$if_updatenr 4}$en‐
1687 dif" shows foo 25% of the time followed by bar 25% of the time
1688 followed by nothing the other half of the time.
1689 if_xmms2_connected
1692 Display everything between $if_xmms2_connected and the matching
1693 $endif if xmms2 is running.
1694 image <path to image> (-p x,y) (-s WxH) (-n) (-f interval)
1697 Renders an image from the path specified using Imlib2. Takes 4
1698 optional arguments: a position, a size, a no-cache switch, and a
1699 cache flush interval. Changing the x,y position will move the
1700 position of the image, and changing the WxH will scale the im‐
1701 age. If you specify the no-cache flag (-n), the image will not
1702 be cached. Alternately, you can specify the -f int switch to
1703 specify a cache flush interval for a particular image. Example:
1704 ${image /home/brenden/cheeseburger.jpg -p 20,20 -s 200x200} will
1705 render 'cheeseburger.jpg' at (20,20) scaled to 200x200 pixels.
1706 Conky does not make any attempt to adjust the position (or any
1707 other formatting) of images, they are just rendered as per the
1708 arguments passed. The only reason $image is part of the
1709 conky.text section, is to allow for runtime modifications,
1710 through $execp $lua_parse, or some other method.
1711 imap_messages (args)
1714 Displays the number of messages in your global IMAP inbox by de‐
1715 fault. You can define individual IMAP inboxes separately by
1716 passing arguments to this object. Arguments are: "host user pass
1717 [-i interval (in seconds)] [-f 'folder'] [-p port] [-e 'com‐
1718 mand'] [-r retries]". Default port is 143, default folder is
1719 'INBOX', default interval is 5 minutes, and default number of
1720 retries before giving up is 5. If the password is supplied as
1721 '*', you will be prompted to enter the password when Conky
1722 starts.
1723 imap_unseen (args)
1726 Displays the number of unseen messages in your global IMAP inbox
1727 by default. You can define individual IMAP inboxes separately by
1728 passing arguments to this object. Arguments are: "host user pass
1729 [-i interval (in seconds)] [-f 'folder'] [-p port] [-e 'com‐
1730 mand'] [-r retries]". Default port is 143, default folder is
1731 'INBOX', default interval is 5 minutes, and default number of
1732 retries before giving up is 5. If the password is supplied as
1733 '*', you will be prompted to enter the password when Conky
1734 starts.
1735 ioscheduler disk
1738 Prints the current ioscheduler used for the given disk name
1739 (i.e. e.g. "hda" or "sdb").
1740 journal lines (type)
1743 Displays last N lines of the systemd journal. The optional type
1744 can be 'user' or 'system' which will show only the user or sys‐
1745 tem journal respectively. By default, all journal lines visible
1746 to the user are shown. A maximum of 200 lines can be displayed,
1747 or until the text buffer is filled.
1748 kernel Kernel version.
1751 key_caps_lock
1754 An indicator for Capital Lock key.
1755 key_num_lock
1758 An indicator for Number Lock key.
1759 key_scroll_lock
1762 An indicator for Scrolling Lock key.
1763 keyboard_layout
1766 Display keyboard layout.
1767 version
1770 Git version number. DragonFly only.
1771 laptop_mode
1774 The value of /proc/sys/vm/laptop_mode.
1775 lines textfile
1778 Displays the number of lines in the given file.
1779 loadavg (1|2|3)
1782 System load average, 1 is for past 1 minute, 2 for past 5 min‐
1783 utes and 3 for past 15 minutes. Without argument, prints all
1784 three values separated by whitespace.
1785 loadgraph (height),(width) (gradient colour 1) (gradient colour 2)
1788 (scale) (-t) (-l)
1789 Load1 average graph, similar to xload, with optional colours in
1790 hex, minus the #. Uses a logarithmic scale (to see small num‐
1791 bers) when you use the -l switch. Takes the switch '-t' to use a
1792 temperature gradient, which makes the gradient values change de‐
1793 pending on the amplitude of a particular graph value (try it and
1794 see).
1795 lua function_name (function parameters)
1798 Executes a Lua function with given parameters, then prints the
1799 returned string. See also 'lua_load' on how to load scripts.
1800 Conky puts 'conky_' in front of function_name to prevent acci‐
1801 dental calls to the wrong function unless you put you place
1802 'conky_' in front of it yourself.
1803 lua_bar (height, width) function_name (function parameters)
1806 Executes a Lua function with given parameters and draws a bar.
1807 Expects result value to be an integer between 0 and 100. See al‐
1808 so 'lua_load' on how to load scripts. Conky puts 'conky_' in
1809 front of function_name to prevent accidental calls to the wrong
1810 function unless you put you place 'conky_' in front of it your‐
1811 self.
1812 lua_gauge (height, width) function_name (function parameters)
1815 Executes a Lua function with given parameters and draws a gauge.
1816 Expects result value to be an integer between 0 and 100. See al‐
1817 so 'lua_load' on how to load scripts. Conky puts 'conky_' in
1818 front of function_name to prevent accidental calls to the wrong
1819 function unless you put you place 'conky_' in front of it your‐
1820 self.
1821 lua_graph function_name (height),(width) (gradient colour 1) (gradient
1824 colour 2) (scale) (-t) (-l)
1825 Executes a Lua function with and draws a graph. Expects result
1826 value to be any number, and by default will scale to show the
1827 full range. See also 'lua_load' on how to load scripts. Takes
1828 the switch '-t' to use a temperature gradient, which makes the
1829 gradient values change depending on the amplitude of a particu‐
1830 lar graph value (try it and see). Conky puts 'conky_' in front
1831 of function_name to prevent accidental calls to the wrong func‐
1832 tion unless you put you place 'conky_' in front of it yourself.
1833 lua_parse function_name (function parameters)
1836 Executes a Lua function with given parameters as per $lua, then
1837 parses and prints the result value as per the syntax for the
1838 conky.text section. See also 'lua_load' on how to load scripts.
1839 Conky puts 'conky_' in front of function_name to prevent acci‐
1840 dental calls to the wrong function unless you put you place
1841 'conky_' in front of it yourself.
1842 machine
1845 Machine, e.g. i686, x86_64.
1846 mails (mailbox) (interval)
1849 Mail count in the specified mailbox or your mail spool if not.
1850 Both mbox and maildir type mailboxes are supported. You can use
1851 a program like fetchmail to get mails from some server using
1852 your favourite protocol. See also new_mails.
1853 mboxscan (-n number of messages to print) (-fw from width) (-sw subject
1856 width) mbox
1857 Print a summary of recent messages in an mbox format mailbox.
1858 mbox parameter is the filename of the mailbox (can be encapsu‐
1859 lated using '"', ie. ${mboxscan -n 10 "/home/brenden/some box"}
1860 mem Amount of memory in use.
1863 memwithbuffers
1866 Amount of memory in use, including that used by system buffers
1867 and caches.
1868 membar (height),(width)
1871 Bar that shows amount of memory in use.
1872 memwithbuffersbar (height),(width)
1875 Bar that shows amount of memory in use (including memory used by
1876 system buffers and caches).
1877 memwithbuffersgraph (height),(width) (gradient colour 1) (gradient
1880 colour 2) (scale) (-t) (-l)
1881 Memory usage graph including memory used by system buffers and
1882 cache. Uses a logarithmic scale (to see small numbers) when you
1883 use the -l switch. Takes the switch '-t' to use a temperature
1884 gradient, which makes the gradient values change depending on
1885 the amplitude of a particular graph value (try it and see).
1886 memdirty
1889 Amount of "dirty" memory. Linux only.
1890 memeasyfree
1893 Amount of free memory including the memory that is very easily
1894 freed (buffers/cache).
1895 memfree
1898 Amount of free memory.
1899 memgauge (height),(width)
1902 Gauge that shows amount of memory in use (see cpugauge).
1903 memgraph (height),(width) (gradient colour 1) (gradient colour 2)
1906 (scale) (-t) (-l)
1907 Memory usage graph. Uses a logarithmic scale (to see small num‐
1908 bers) when you use the -l switch. Takes the switch '-t' to use a
1909 temperature gradient, which makes the gradient values change de‐
1910 pending on the amplitude of a particular graph value (try it and
1911 see).
1912 memmax Total amount of memory.
1915 memperc
1918 Percentage of memory in use.
1919 mixer (device)
1922 Prints the mixer value as reported by the OS. On Linux, this
1923 variable uses the OSS emulation, so you need the proper kernel
1924 module loaded. Default mixer is "Vol", but you can specify one
1925 of the available OSS controls: "Vol", "Bass", "Trebl", "Synth",
1926 "Pcm", "Spkr", "Line", "Mic", "CD", "Mix", "Pcm2 ", "Rec",
1927 "IGain", "OGain", "Line1", "Line2", "Line3", "Digital1", "Digi‐
1928 tal2", "Digital3", "PhoneIn", "PhoneOut", "Video", "Radio" and
1929 "Monitor".
1930 mixerbar (device)
1933 Displays mixer value in a bar as reported by the OS. See docs
1934 for $mixer for details on arguments.
1935 mixerl (device)
1938 Prints the left channel mixer value as reported by the OS. See
1939 docs for $mixer for details on arguments.
1940 mixerlbar (device)
1943 Displays the left channel mixer value in a bar as reported by
1944 the OS. See docs for $mixer for details on arguments.
1945 mixerr (device)
1948 Prints the right channel mixer value as reported by the OS. See
1949 docs for $mixer for details on arguments.
1950 mixerrbar (device)
1953 Displays the right channel mixer value in a bar as reported by
1954 the OS. See docs for $mixer for details on arguments.
1955 moc_album
1958 Album of the current MOC song.
1959 moc_artist
1962 Artist of the current MOC song.
1963 moc_bitrate
1966 Bitrate in the current MOC song.
1967 moc_curtime
1970 Current time of the current MOC song.
1971 moc_file
1974 File name of the current MOC song.
1975 moc_rate
1978 Rate of the current MOC song.
1979 moc_song
1982 The current song name being played in MOC.
1983 moc_state
1986 Current state of MOC; playing, stopped etc.
1987 moc_timeleft
1990 Time left in the current MOC song.
1991 moc_title
1994 Title of the current MOC song.
1995 moc_totaltime
1998 Total length of the current MOC song.
1999 monitor
2002 Number of the monitor on which conky is running or the message
2003 "Not running in X" if this is the case.
2004 monitor_number
2007 Number of monitors or the message "Not running in X" if this is
2008 the case.
2009 mouse_speed
2012 Display mouse speed.
2013 mpd_album
2016 Album in current MPD song.
2017 mpd_artist
2020 Artist in current MPD song must be enabled at compile.
2021 mpd_albumartist
2024 Artist of the album of the current MPD song.
2025 mpd_bar (height),(width)
2028 Bar of mpd's progress.
2029 mpd_bitrate
2032 Bitrate of current song.
2033 mpd_date
2036 Date of current song.
2037 mpd_elapsed
2040 Song's elapsed time.
2041 mpd_file
2044 Prints the file name of the current MPD song.
2045 mpd_length
2048 Song's length.
2049 mpd_name
2052 Prints the MPD name field.
2053 mpd_percent
2056 Percent of song's progress.
2057 mpd_random
2060 Random status (On/Off).
2061 mpd_repeat
2064 Repeat status (On/Off).
2065 mpd_smart (max length)
2068 Prints the song name in either the form "artist - title" or file
2069 name, depending on whats available.
2070 mpd_status
2073 Playing, stopped, et cetera.
2074 mpd_title (max length)
2077 Title of current MPD song.
2078 mpd_track
2081 Prints the MPD track field.
2082 mpd_vol
2085 MPD's volume.
2086 mysql query
2089 Shows the first field of the first row of the result of the
2090 query.
2091 nameserver (index)
2094 Print a nameserver from /etc/resolv.conf. Index starts at and
2095 defaults to 0.
2096 new_mails (mailbox) (interval)
2099 Unread mail count in the specified mailbox or mail spool if not.
2100 Both mbox and maildir type mailboxes are supported.
2101 nodename
2104 Hostname.
2105 nodename_short
2108 Short hostname (same as 'hostname -s' shell command).
2109 no_update text
2112 Shows text and parses the vars in it, but doesn't update them.
2113 Use this for things that do not change while conky is running,
2114 like $machine, $conky_version,... By not updating this you can
2115 save some resources.
2116 nvidia argument (GPU_ID)
2119 Nvidia graphics card information via the XNVCtrl library.
2120 GPU_ID:Optional parameter to choose the GPU to be used as
2122 0,1,2,3,.. Default parameter is 0
2123 Possible arguments:(Temperatures are printed as float, all other
2125 values as integer. Bracketed arguments are aliases)
2126 gputemp( temp) GPU temperature
2128 gputempthreshold( threshold) Temperature threshold where the GPU
2129 will reduce it's clock speed
2130 ambienttemp( ambient) Ambient temperature outside the graphics
2131 card
2132 gpufreqcur( gpufreq) Current GPU clock speed
2133 gpufreqmin Minimum GPU clock speed
2134 gpufreqmax Maximum GPU clock speed
2135 memfreqcur( memfreq) Current memory clock speed
2136 memfreqmin Minimum memory clock speed
2137 memfreqmax Maximum memory clock speed
2138 mtrfreqcur( mtrfreq) Current memory transfer rate clock speed
2139 mtrfreqmin Minimum memory transfer rate clock speed
2140 mtrfreqmax Maximum memory transfer rate clock speed
2141 perflevelcur( perflevel) Current performance level
2142 perflevelmin Lowest performance level
2143 perflevelmax Highest performance level
2144 perfmode Performance mode
2145 gpuutil GPU utilization %
2146 membwutil Memory bandwidth utilization %
2147 videoutil Video engine utilization %
2148 pcieutil PCIe bandwidth utilization %
2149 memused( mem) Amount of used memory
2150 memfree( memavail) Amount of free memory
2151 memmax( memtotal) Total amount of memory
2152 memutil( memperc) Memory utilization %
2153 fanspeed Fan speed
2154 fanlevel Fan level %
2155 imagequality Image quality
2156 modelname name of the GPU card
2157 nvidiabar (height),(width) argument (GPU_ID)
2159 Same as nvidia, except it draws its output in a horizontal bar.
2160 The height and width parameters are optional, and default to the
2161 default_bar_height and default_bar_width config settings, re‐
2162 spectively.
2163 GPU_ID:Optional parameter to choose the GPU to be used as
2165 0,1,2,3,.. Default parameter is 0
2166 Note the following arguments are incompatible: gputempthreshold(
2168 threshold)
2169 gpufreqmin
2170 gpufreqmax
2171 memfreqmin
2172 memfreqmax
2173 mtrfreqmin
2174 mtrfreqmax
2175 perflevelmin
2176 perflevelmax
2177 perfmode
2178 memtotal( memmax)
2179 fanspeed
2180 nvidiagauge (height),(width) argument (GPU_ID)
2182 Same as nvidiabar, except a round gauge (much like a vehicle
2183 speedometer). The height and width parameters are optional, and
2184 default to the default_gauge_height and default_gauge_width con‐
2185 fig settings, respectively.
2186 GPU_ID:Optional parameter to choose the GPU to be used as
2188 0,1,2,3,.. Default parameter is 0
2189 For possible arguments see nvidia and nvidiabar.
2191 nvidiagraph argument (height),(width) (gradient color 1) (gradient col‐
2193 or 2) (scale) (-t) (-l) GPU_ID
2194 Same as nvidiabar, except a horizontally scrolling graph with
2195 values from 0-100 plotted on the vertical axis. The height and
2196 width parameters are optional, and default to the de‐
2197 fault_graph_height and default_graph_width config settings, re‐
2198 spectively.
2199 GPU_ID:NOT optional. This parameter allows to choose the GPU to
2201 be used as 0,1,2,3,..
2202 For possible arguments see nvidia and nvidiabar. To learn more
2204 about the -t -l and gradient color options, see execgraph.
2205 offset (pixels)
2207 Move text over by N pixels. See also $voffset.
2208 outlinecolor (color)
2211 Change outline color.
2212 password (length)
2215 Generate random passwords.
2216 pa_sink_volume
2219 Pulseaudio's default sink volume percentage.
2220 pa_sink_volumebar
2223 Pulseaudio's default sink volume bar.
2224 pa_sink_description
2227 Pulseaudio's default sink description.
2228 pa_sink_active_port_name
2231 Pulseaudio's default sink active port name.
2232 pa_sink_active_port_description
2235 Pulseaudio's default sink active port description.
2236 pa_card_name
2239 Pulseaudio's default card name.
2240 pa_card_active_profile
2243 Pulseaudio's default card active profile.
2244 pb_battery item
2247 If running on Apple powerbook/ibook, display information on bat‐
2248 tery status. The item parameter specifies, what information to
2249 display. Exactly one item must be specified. Valid items are:
2250 status Display if battery is fully charged, charging, discharg‐
2252 ing or absent (running on AC)
2253 percent Display charge of battery in percent, if charging or
2254 discharging. Nothing will be displayed, if battery is fully
2255 charged or absent.
2256 time Display the time remaining until the battery will be fully
2257 charged or discharged at current rate. Nothing is displayed, if
2258 battery is absent or if it's present but fully charged and not
2259 discharging.
2260 pid_chroot pid
2263 Directory used as rootdirectory by the process (this will be "/"
2264 unless the process did a chroot syscall).
2265 pid_cmdline pid
2268 Command line this process was invoked with.
2269 pid_cwd pid
2272 Current working directory of the process.
2273 pid_environ pid varname
2276 Contents of a environment-var of the process.
2277 pid_environ_list pid
2280 List of environment-vars that the process can see.
2281 pid_exe pid
2284 Path to executed command that started the process.
2285 pid_nice pid
2288 The nice value of the process.
2289 pid_openfiles pid
2292 List of files that the process has open.
2293 pid_parent pid
2296 The pid of the parent of the process.
2297 pid_priority pid
2300 The priority of the process (see 'priority' in "man 5 proc").
2301 pid_read pid
2304 Total number of bytes read by the process.
2305 pid_state pid
2308 State of the process.
2309 pid_state_short pid
2312 One of the chars in "RSDZTW" representing the state of the
2313 process where R is running, S is sleeping in an interruptible
2314 wait, D is waiting in uninterruptible disk sleep, Z is zombie, T
2315 is traced or stopped (on a signal), and W is paging.
2316 pid_stderr pid
2319 Filedescriptor binded to the STDERR of the process.
2320 pid_stdin pid
2323 Filedescriptor binded to the STDIN of the process.
2324 pid_stdout pid
2327 Filedescriptor binded to the STDOUT of the process.
2328 pid_threads pid
2331 Number of threads in process containing this thread.
2332 pid_thread_list pid
2335 List with pid's from threads from this process.
2336 pid_time_kernelmode pid
2339 Amount of time that the process has been scheduled in kernel
2340 mode in seconds.
2341 pid_time_usermode pid
2344 Amount of time that the process has been scheduled in user mode
2345 in seconds.
2346 pid_time pid
2349 Sum of $pid_time_kernelmode and $pid_time_usermode.
2350 pid_uid pid
2353 The real uid of the process.
2354 pid_euid pid
2357 The effective uid of the process.
2358 pid_suid pid
2361 The saved set uid of the process.
2362 pid_fsuid pid
2365 The file system uid of the process.
2366 pid_gid pid
2369 The real gid of the process.
2370 pid_egid pid
2373 The effective gid of the process.
2374 pid_sgid pid
2377 The saved set gid of the process.
2378 pid_fsgid pid
2381 The file system gid of the process.
2382 pid_vmpeak pid
2385 Peak virtual memory size of the process.
2386 pid_vmsize pid
2389 Virtual memory size of the process.
2390 pid_vmlck pid
2393 Locked memory size of the process.
2394 pid_vmhwm pid
2397 Peak resident set size ("high water mark") of the process.
2398 pid_vmrss pid
2401 Resident set size of the process.
2402 pid_vmdata pid
2405 Data segment size of the process.
2406 pid_vmstk pid
2409 Stack segment size of the process.
2410 pid_vmexe pid
2413 Text segment size of the process.
2414 pid_vmlib pid
2417 Shared library code size of the process.
2418 pid_vmpte pid
2421 Page table entries size of the process.
2422 pid_write pid
2425 Total number of bytes written by the process.
2426 platform (dev) type n (factor offset)
2429 Platform sensor from sysfs (Linux 2.6). Parameter dev may be
2430 omitted if you have only one platform device. Platform type is
2431 either 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp'
2432 meaning temperature. Parameter n is number of the sensor. See
2433 /sys/bus/platform/devices/ on your local computer. The optional
2434 arguments 'factor' and 'offset' allow precalculation of the raw
2435 input, which is being modified as follows: 'input = input * fac‐
2436 tor + offset'. Note that they have to be given as decimal values
2437 (i.e. contain at least one decimal place).
2438 pop3_unseen (args)
2441 Displays the number of unseen messages in your global POP3 inbox
2442 by default. You can define individual POP3 inboxes separately by
2443 passing arguments to this object. Arguments are: "host user pass
2444 [-i interval (in seconds)] [-p port] [-e 'command'] [-r re‐
2445 tries]". Default port is 110, default interval is 5 minutes, and
2446 default number of retries before giving up is 5. If the password
2447 is supplied as '*', you will be prompted to enter the password
2448 when Conky starts.
2449 pop3_used (args)
2452 Displays the amount of space (in MiB, 2^20) used in your global
2453 POP3 inbox by default. You can define individual POP3 inboxes
2454 separately by passing arguments to this object. Arguments are:
2455 "host user pass [-i interval (in seconds)] [-p port] [-e 'com‐
2456 mand'] [-r retries]". Default port is 110, default interval is 5
2457 minutes, and default number of retries before giving up is 5. If
2458 the password is supplied as '*', you will be prompted to enter
2459 the password when Conky starts.
2460 processes
2463 Total processes (sleeping and running).
2464 read_tcp (host) port
2467 Connects to a tcp port on a host (default is localhost), reads
2468 every char available at the moment and shows them.
2469 read_udp (host) port
2472 Connects to a udp port on a host (default is localhost), reads
2473 every char available at the moment and shows them.
2474 replied_mails (maildir) (interval)
2477 Number of mails marked as replied in the specified mailbox or
2478 mail spool if not. Only maildir type mailboxes are supported,
2479 mbox type will return -1.
2480 rss uri interval_in_seconds action (num_par (spaces_in_front))
2483 Download and parse RSS feeds. The interval may be a (floating
2484 point) value greater than 0. Action may be one of the following:
2485 feed_title, item_title (with num par), item_desc (with num par)
2486 and item_titles (when using this action and spaces_in_front is
2487 given conky places that many spaces in front of each item). This
2488 object is threaded, and once a thread is created it can't be ex‐
2489 plicitly destroyed. One thread will run for each URI specified.
2490 You can use any protocol that Curl supports.
2491 running_processes
2494 Running processes (not sleeping). Requires Linux 2.6.
2495 running_threads
2498 Number of running (runnable) threads. Linux only.
2499 scroll (direction) length (step) (interval) text
2502 Scroll 'text' by 'step' characters to the left or right (set
2503 'direction' to 'left' or 'right' or 'wait') showing 'length'
2504 number of characters at the same time. The text may also contain
2505 variables. 'step' is optional and defaults to 1 if not set.
2506 'direction' is optional and defaults to left if not set. When
2507 direction is 'wait' then text will scroll left and wait for 'in‐
2508 terval' itertations at the beginning and end of the text. If a
2509 var creates output on multiple lines then the lines are placed
2510 behind each other separated with a '|'-sign. If you change the
2511 textcolor inside $scroll it will automatically have it's old
2512 value back at the end of $scroll. The end and the start of text
2513 will be separated by 'length' number of spaces unless direction
2514 is 'wait'.
2515 seen_mails (maildir) (interval)
2518 Number of mails marked as seen in the specified mailbox or mail
2519 spool if not. Only maildir type mailboxes are supported, mbox
2520 type will return -1.
2521 sip_status (switch)
2524 Prints info regarding System Integrity Protection (SIP) on mac‐
2525 OS. If no switch is provided, prints SIP status (enabled / dis‐
2526 abled), else, status of the specific SIP feature corresponding
2527 to the switch provided. Below are shown the available switches:
2528 SWITCH--------------------------RE‐
2529 SULT--------------------------STATUS 0 apple internal YES/NO 1
2530 forbid untrusted kexts YES/NO 2 forbid task-for-pid YES/NO 3 re‐
2531 strict filesystem YES/NO 4 forbid kernel-debugger YES/NO 5 re‐
2532 strict dtrace YES/NO 6 restrict nvram YES/NO 7 forbid device-
2533 configuration YES/NO 8 forbid any-recovery-os YES/NO 9 forbid
2534 user-approved-kexts YES/NO a uses unsupported configuration? (*)
2535 (*): If yes, prints "unsupported configuration, beware!" Else,
2536 prints "configuration is ok".
2537 ----------------------------------------------------------------------
2538 USAGE: conky -t '${sip_status}' # print SIP status conky -t
2539 '${sip_status 0}' # print allows apple-internal? Yes or No?
2540 NOTES: * Available for all macOS versions (even the ones prior
2541 El Capitan where SIP was first introduced) * If run on versions
2542 prior El Capitan SIP is unavailable, so all you will get is "un‐
2543 supported".
2544 shadecolor (color)
2547 Change shading color.
2548 smapi (ARGS)
2551 when using smapi, display contents of the /sys/devices/plat‐
2552 form/smapi directory. ARGS are either '(FILENAME)' or 'bat (IN‐
2553 DEX) (FILENAME)' to display the corresponding files' content.
2554 This is a very raw method of accessing the smapi values. When
2555 available, better use one of the smapi_* variables instead.
2556 smapi_bat_bar (INDEX),(height),(width)
2559 when using smapi, display the remaining capacity of the battery
2560 with index INDEX as a bar.
2561 smapi_bat_perc (INDEX)
2564 when using smapi, display the remaining capacity in percent of
2565 the battery with index INDEX. This is a separate variable be‐
2566 cause it supports the 'use_spacer' configuration option.
2567 smapi_bat_power INDEX
2570 when using smapi, display the current power of the battery with
2571 index INDEX in watt. This is a separate variable because the
2572 original read out value is being converted from mW. The sign of
2573 the output reflects charging (positive) or discharging (nega‐
2574 tive) state.
2575 smapi_bat_temp INDEX
2578 when using smapi, display the current temperature of the battery
2579 with index INDEX in degree Celsius. This is a separate variable
2580 because the original read out value is being converted from mil‐
2581 li degree Celsius.
2582 sony_fanspeed
2585 Displays the Sony VAIO fanspeed information if sony-laptop ker‐
2586 nel support is enabled. Linux only.
2587 start_case text
2590 All words capitalized regardless.
2591 stippled_hr (space)
2594 Stippled (dashed) horizontal line.
2595 stock symbol data
2598 Displays the data of a stock symbol. The following data is sup‐
2599 ported: adv(Average Daily Volume), ask, asksize, bid, askrt(ask
2600 realtime), bidrt(bid realtime), bookvalue, bidsize, change, com‐
2601 mission, changert(change realtime), ahcrt(After Hours Change re‐
2602 altime), ds(dividend/share), ltd(Last Trade Date), tradedate,
2603 es(earnings/share), ei(error indication), epsecy(EPS Estimate
2604 Current Year), epseny(EPS Estimate Next Year), epsenq(EPS Esti‐
2605 mate Next Quarter), floatshares, dayslow, dayshigh, 52weeklow,
2606 52weekhigh, hgp(Holdings Gain Percent), ag(Annualized Gain),
2607 hg(Holdings Gain), hgprt(Holdings Gain Percent realtime),
2608 hgrt(Holdings Gain realtime), moreinfo, obrt(Order Book real‐
2609 time), mc(Market Capitalization), mcrt(Market Cap realtime),
2610 ebitda, c52wlow(Change From 52-week Low), pc52wlow(Percent
2611 Change From 52-week Low), cprt(change percent realtime),
2612 lts(Last Trade Size), c52whigh(Change from 52-week high),
2613 pc52whigh(percent change from 52-week high), ltp(last trade
2614 price), hl(high limit), ll(low limit), dr(day's range), dr‐
2615 rt(day's range realtime), 50ma(50-day Moving Average),
2616 200ma(200-day Moving Average), c200ma(Change From 200-day Moving
2617 Average), pc200ma(Percent Change From 200-day Moving Average),
2618 c50ma(Change From 50-day Moving Average), pc50ma(Percent Change
2619 From 50-day Moving Average), name, notes, open, pc(previous
2620 close), pricepaid, cip(change in percent), ps(price/sales),
2621 pb(price/book), edv(Ex-Dividend Date), per(P/E Ratio), dpd(Divi‐
2622 dend Pay Date), perrt(P/E Ratio realtime), pegr(PEG Ratio),
2623 pepsecy(Price/EPS Estimate Current Year), pepseny(Price/EPS Es‐
2624 timate Next Year), symbol, sharesowned, shortratio, ltt(Last
2625 Trade Time), tradelinks, tt(Ticker Trend), 1ytp(1 yr Target
2626 Price), volume, hv(Holdings Value), hvrt(Holdings Value real‐
2627 time), 52weekrange, dvc(Day's Value Change), dvcrt(Day's Value
2628 Change realtime), se(Stock Exchange), dy(Dividend Yield).
2629 swap Amount of swap in use.
2632 swapbar (height),(width)
2635 Bar that shows amount of swap in use.
2636 swapfree
2639 Amount of free swap.
2640 swapmax
2643 Total amount of swap.
2644 swapperc
2647 Percentage of swap in use.
2648 sysname
2651 System name, e.g. Linux.
2652 sysctlbyname (name)
2655 Print sysctl value by name. FreeBSD only.
2656 tab (width, (start))
2659 Puts a tab of the specified width, starting from column 'start'.
2660 The unit is pixels for both arguments.
2661 tail logfile lines (next_check)
2664 Displays last N lines of supplied text file. The file is checked
2665 every 'next_check' update. If next_check is not supplied, Conky
2666 defaults to 2. Max of 30 lines can be displayed, or until the
2667 text buffer is filled.
2668 tcp_ping host (port)
2671 Displays the number of microseconds it takes to get a reply on a
2672 ping to to tcp 'port' on 'host'. 'port' is optional and has 80
2673 as default. This works on both open and closed ports, just make
2674 sure that the port is not behind a firewall or you will get
2675 'down' as answer. It's best to test a closed port instead of an
2676 open port, you will get a quicker response.
2677 tcp_portmon port_begin port_end item (index)
2680 TCP port (both IPv6 and IPv4) monitor for specified local ports.
2681 Port numbers must be in the range 1 to 65535. Valid items are:
2682 count Total number of connections in the range
2684 rip Remote ip address
2685 rhost Remote host name
2686 rport Remote port number
2687 rservice Remote service name from /etc/services
2688 lip Local ip address
2689 lhost Local host name
2690 lport Local port number
2691 lservice Local service name from /etc/services
2692 The connection index provides you with access to each connection
2694 in the port monitor. The monitor will return information for in‐
2695 dex values from 0 to n-1 connections. Values higher than n-1 are
2696 simply ignored. For the "count" item, the connection index must
2697 be omitted. It is required for all other items.
2698 Examples:
2700 ${tcp_portmon 6881 6999 count} Displays the number of connec‐
2702 tions in the bittorrent port range
2703 ${tcp_portmon 22 22 rip 0} Displays the remote host ip of the
2704 first sshd connection
2705 ${tcp_portmon 22 22 rip 9} Displays the remote host ip of the
2706 tenth sshd connection
2707 ${tcp_portmon 1 1024 rhost 0} Displays the remote host name of
2708 the first connection on a privileged port
2709 ${tcp_portmon 1 1024 rport 4} Displays the remote host port of
2710 the fifth connection on a privileged port
2711 ${tcp_portmon 1 65535 lservice 14} Displays the local service
2712 name of the fifteenth connection in the range of all ports
2713 Note that port monitor variables which share the same port range
2715 actually refer to the same monitor, so many references to a sin‐
2716 gle port range for different items and different indexes all use
2717 the same monitor internally. In other words, the program avoids
2718 creating redundant monitors.
2719 templateN (arg1) (arg2) (arg3 ...)
2721 Evaluate the content of the templateN configuration variable
2722 (where N is a value between 0 and 9, inclusively), applying sub‐
2723 stitutions as described in the documentation of the correspond‐
2724 ing configuration variable. The number of arguments is optional,
2725 but must match the highest referred index in the template. You
2726 can use the same special sequences in each argument as the ones
2727 valid for a template definition, e.g. to allow an argument to
2728 contain a whitespace. Also simple nesting of templates is possi‐
2729 ble this way.
2730 Here are some examples of template definitions, note they are
2732 placed between [[ ... ]] instead of ' ... ':
2733 template0 = [[$\1\2]]
2735 template1 = [[\1: ${fs_used \2} / ${fs_size \2}]]
2736 template2 = [[\1 \2]]
2737 The following list shows sample usage of the templates defined
2739 above, with the equivalent syntax when not using any template at
2740 all:
2741 using template same without template
2743 ────────────────────────────────────────────────────────
2744 ${template0 node name} $nodename
2745 ${template1 root /} root: ${fs_free /} /
2746 ${fs_size /}
2747 ${template1 ${template2\ disk root: ${fs_free /} /
2748 disk\ root} /} ${fs_size /}
2749 texeci interval command
2751 Runs a command at an interval inside a thread and displays the
2752 output. Same as $execi, except the command is run inside a
2753 thread. Use this if you have a slow script to keep Conky updat‐
2754 ing. You should make the interval slightly longer than the time
2755 it takes your script to execute. For example, if you have a
2756 script that take 5 seconds to execute, you should make the in‐
2757 terval at least 6 seconds. See also $execi. This object will
2758 clean up the thread when it is destroyed, so it can safely be
2759 used in a nested fashion, though it may not produce the desired
2760 behaviour if used this way.
2761 texecpi interval command
2764 Same as execpi, except the command is run inside a thread.
2765 threads
2768 Total threads.
2769 time (format)
2772 Local time, see "man strftime" to get more information about
2773 format.
2774 to_bytes size
2777 If 'size' is a number followed by a size-unit (kilo‐
2778 byte,mb,GiB,...) then it converts the size to bytes and shows it
2779 without unit, otherwise it just shows 'size'.
2780 top type num
2783 This takes arguments in the form:top (name) (number) Basically,
2784 processes are ranked from highest to lowest in terms of cpu us‐
2785 age, which is what (num) represents. The types are: "name",
2786 "pid", "cpu", "mem", "mem_res", "mem_vsize", "time", "uid", "us‐
2787 er", "io_perc", "io_read" and "io_write". There can be a max of
2788 10 processes listed.
2789 top_io type num
2792 Same as top, except sorted by the amount of I/O the process has
2793 done during the update interval.
2794 top_mem type num
2797 Same as top, except sorted by mem usage instead of cpu.
2798 top_time type num
2801 Same as top, except sorted by total CPU time instead of current
2802 CPU usage.
2803 totaldown (net)
2806 Total download, overflows at 4 GB on Linux with 32-bit arch and
2807 there doesn't seem to be a way to know how many times it has al‐
2808 ready done that before conky has started.
2809 totalup (net)
2812 Total upload, this one too, may overflow.
2813 trashed_mails (maildir) (interval)
2816 Number of mails marked as trashed in the specified mailbox or
2817 mail spool if not. Only maildir type mailboxes are supported,
2818 mbox type will return -1.
2819 tztime (timezone (format))
2822 Local time for specified timezone, see man strftime to get more
2823 information about format. The timezone argument is specified in
2824 similar fashion as TZ environment variable. For hints, look in
2825 /usr/share/zoneinfo. e.g. US/Pacific, Europe/Zurich, etc.
2826 gid_name gid
2829 Name of group with this gid.
2830 uid_name uid
2833 Username of user with this uid.
2834 unflagged_mails (maildir) (interval)
2837 Number of mails not marked as flagged in the specified mailbox
2838 or mail spool if not. Only maildir type mailboxes are supported,
2839 mbox type will return -1.
2840 unforwarded_mails (maildir) (interval)
2843 Number of mails not marked as forwarded in the specified mailbox
2844 or mail spool if not. Only maildir type mailboxes are supported,
2845 mbox type will return -1.
2846 unreplied_mails (maildir) (interval)
2849 Number of mails not marked as replied in the specified mailbox
2850 or mail spool if not. Only maildir type mailboxes are supported,
2851 mbox type will return -1.
2852 unseen_mails (maildir) (interval)
2855 Number of new or unseen mails in the specified mailbox or mail
2856 spool if not. Only maildir type mailboxes are supported, mbox
2857 type will return -1.
2858 updates Number of updates
2861 for debugging.
2862 upspeed (net)
2865 Upload speed in suitable IEC units.
2866 upspeedf (net)
2869 Upload speed in KiB with one decimal.
2870 upspeedgraph (netdev) (height),(width) (gradient colour 1) (gradient
2873 colour 2) (scale) (-t) (-l)
2874 Upload speed graph, colours defined in hex, minus the #. If
2875 scale is non-zero, it becomes the scale for the graph. Uses a
2876 logarithmic scale (to see small numbers) when you use the -l
2877 switch. Takes the switch '-t' to use a temperature gradient,
2878 which makes the gradient values change depending on the ampli‐
2879 tude of a particular graph value (try it and see).
2880 uptime Uptime.
2883 uptime_short
2886 Uptime in a shorter format.
2887 user_names
2890 Lists the names of the users logged in.
2891 user_number
2894 Number of users logged in.
2895 user_terms
2898 Lists the consoles in use.
2899 user_times
2902 Lists how long users have been logged in for.
2903 user_time console
2906 Lists how long the user for the given console has been logged in
2907 for.
2908 utime (format)
2911 Display time in UTC (universal coordinate time).
2912 v6addrs (-n) (-s) (interface)
2915 IPv6 addresses for an interface, followed by netmask if -n is
2916 specified and scope with -s. Scopes are Global(G), Host-lo‐
2917 cal(H), Link-local(L), Site-local(S), Compat(C) and Unspeci‐
2918 fied(/). Linux only.
2919 voffset (pixels)
2922 Change vertical offset by N pixels. Negative values will cause
2923 text to overlap. See also $offset.
2924 voltage_mv (n)
2927 Returns CPU #n's voltage in mV. CPUs are counted from 1. If
2928 omitted, the parameter defaults to 1.
2929 voltage_v (n)
2932 Returns CPU #n's voltage in V. CPUs are counted from 1. If omit‐
2933 ted, the parameter defaults to 1.
2934 weather URI locID data_type (interval_in_minutes)
2937 Download, parse and display METAR data.
2938 'URI' must be a valid METAR URI.
2940 http://tgftp.nws.noaa.gov/data/observations/metar/stations/
2942 'locID' must be a valid location identifier for the required
2944 uri. For the NOAA site this must be a valid ICAO (see for in‐
2945 stance https://pilotweb.nas.faa.gov/qryhtml/icao/). For the
2946 weather.com site this must be a valid location ID (see for in‐
2947 stance http://aspnetresources.com/tools/locid.aspx).
2948 'data_type' must be one of the following:
2950 last_update The date and time stamp of the data. The result de‐
2952 pends on the URI used. For the NOAA site it is date (yyyy/mm/dd)
2953 and UTC time. For the weather.com one it is date ([m]m/[d]d/yy)
2954 and Local Time of the station.
2955 temperature
2956 Air temperature (you can use the 'temperature_unit' config set‐
2958 ting to change units)
2959 cloud_cover
2960 The highest cloud cover status
2962 pressure
2963 Air pressure in millibar
2965 wind_speed
2966 Wind speed in km/h
2968 wind_dir
2969 Wind direction
2971 wind_dir_DEG
2972 Compass wind direction
2974 humidity
2975 Relative humidity in %
2977 weather
2978 Any relevant weather event (rain, snow, etc.). This is not used
2980 if you are querying the weather.com site since this data is ag‐
2981 gregated into the cloud_cover one
2982 icon
2983 Weather icon (only for www.weather.com). Can be used together
2985 with the icon kit provided upon registering to their service.
2986 'delay_in_minutes' (optional, default 30) cannot be less than 30
2988 minutes.
2989 This object is threaded, and once a thread is created it can't
2991 be explicitly destroyed. One thread will run for each URI speci‐
2992 fied.
2993 Note that these variables are still EXPERIMENTAL and can be sub‐
2995 ject to many future changes.
2996 weather_forecast URI locID day data_type (interval_in_minutes)
2998 Download, parse and display weather forecast data for a given
2999 day (daytime only).
3000 'locID', see 'weather' above.
3002 'day' is a number from 0 (today) to 4 (3 days after tomorrow).
3004 'data_type' must be one of the following:
3006 day Day of the week
3008 date Date, in the form MMM DD (ie. Jul 14)
3009 low Minimun temperature (you can use the 'temperature_unit' con‐
3010 fig setting to change units)
3011 hi Maximum temperature (you can use the 'temperature_unit' con‐
3012 fig setting to change units)
3013 icon Weather icon. Can be used together with the icon kit pro‐
3014 vided upon registering to the weather.com service
3015 forecast Weather forecast (sunny, rainy, etc.)
3016 wind_speed Wind speed in km/h
3017 wind_dir Wind direction
3018 wind_dir_DEG Compass wind direction
3019 humidity Relative humidity in %
3020 precipitation Probability of having a precipitation (in %)
3021 'delay_in_minutes' (optional, default 210) cannot be lower than
3023 210 min.
3024 This object is threaded, and once a thread is created it can't
3026 be explicitly destroyed. One thread will run for each URI speci‐
3027 fied. You can use any protocol that Curl supports.
3028 Note that these variables are still EXPERIMENTAL and can be sub‐
3030 ject to many future changes.
3031 wireless_ap (net)
3033 Wireless access point MAC address. Linux only.
3034 wireless_bitrate (net)
3037 Wireless bitrate (ie 11 Mb/s). Linux only.
3038 wireless_channel (net)
3041 WLAN channel on which device 'net' is listening.
3042 wireless_essid (net)
3045 Wireless access point ESSID. Linux only.
3046 wireless_freq (net)
3049 Frequency on which device 'net' is listening.
3050 wireless_link_bar (height),(width) (net)
3053 Wireless link quality bar. Linux only.
3054 wireless_link_qual (net)
3057 Wireless link quality. Linux only.
3058 wireless_link_qual_max (net)
3061 Wireless link quality maximum value. Linux only.
3062 wireless_link_qual_perc (net)
3065 Wireless link quality in percents. Linux only.
3066 wireless_mode (net)
3069 Wireless mode (Managed/Ad-Hoc/Master). Linux only.
3070 words textfile
3073 Displays the number of words in the given file.
3074 xmms2_album
3077 Album in current XMMS2 song.
3078 xmms2_artist
3081 Artist in current XMMS2 song.
3082 xmms2_bar (height),(width)
3085 Bar of XMMS2's progress.
3086 xmms2_bitrate
3089 Bitrate of current song.
3090 xmms2_comment
3093 Comment in current XMMS2 song.
3094 xmms2_date
3097 Returns song's date.
3098 xmms2_duration
3101 Duration of current song.
3102 xmms2_elapsed
3105 Song's elapsed time.
3106 xmms2_genre
3109 Genre in current XMMS2 song.
3110 xmms2_id
3113 XMMS2 id of current song.
3114 xmms2_percent
3117 Percent of song's progress.
3118 xmms2_playlist
3121 Returns the XMMS2 playlist.
3122 xmms2_size
3125 Size of current song.
3126 xmms2_smart
3129 Prints the song name in either the form "artist - title" or file
3130 name, depending on whats available.
3131 xmms2_status
3134 XMMS2 status (Playing, Paused, Stopped, or Disconnected).
3135 xmms2_timesplayed
3138 Number of times a song was played (presumably).
3139 xmms2_title
3142 Title in current XMMS2 song.
3143 xmms2_tracknr
3146 Track number in current XMMS2 song.
3147 xmms2_url
3150 Full path to current song.
3151
3154 Conky features a Lua Programming API, and also ships with Lua bindings
3155 for some useful libraries. Note that the bindings require tolua++,
3156 which currently only compiles against Lua 5.1.
3157 To use Lua Conky, you first need to make sure you have a version of
3159 Conky with Lua support enabled (``conky -v'' will report this). Conky
3160 defines certain global functions and variables which can be accessed
3161 from Lua code running in Conky. Scripts must first be loaded using the
3162 lua_load configuration option. You then call functions in Lua via
3163 Conky's $lua, $lua_read, and Lua hooks.
3164 Be careful when creating threaded objects through the Lua API. You
3166 could wind up with a whole bunch of threads running if a thread is cre‐
3167 ated with each iteration.
3168 At this time, the Lua API should not be considered stable and may
3170 change drastically from one release to another as it matures.
3171 NOTE: In order to accommodate certain features in the cairo library's
3173 API, Conky will export a few additional functions for the creation of
3174 certain structures. These are documented below.
3175 conky_parse(string) function
3177 This function takes a string that is evaluated as per Conky's
3178 TEXT section, and then returns a string with the result.
3179 conky_set_update_interval(number) function
3181 Sets Conky's update interval (in seconds) to 'number'.
3182 conky_window table
3184 This table contains some information about Conky's window. The
3185 following table describes the values contained:
3186 drawable Window's drawable (Xlib Drawable), requires Lua extras
3188 enabled at compile time.
3189 visual Window's visual (Xlib Visual), requires Lua extras en‐
3190 abled at compile time.
3191 display Window's display (Xlib Display), requires Lua extras en‐
3192 abled at compile time.
3193 width Window width (in pixels).
3194 height Window height (in pixels).
3195 border_inner_margin Window's inner border margin (in pixels).
3196 border_outer_margin Window's outer border margin (in pixels).
3197 border_width Window's border width (in pixels).
3198 text_start_x The x component of the starting coordinate of text
3199 drawing.
3200 text_start_y The y component of the starting coordinate of text
3201 drawing.
3202 text_width The width of the text drawing region.
3203 text_height The height of the text drawing region.
3204 NOTE: This table is only defined when X support is enabled.
3206 conky_info table
3208 This table contains some information about Conky's internal da‐
3209 ta. The following table describes the values contained:
3210 update_interval Conky's update interval (in seconds).
3212 conky_build_info string
3214 A string containing the build info for this particular instance
3215 of Conky, including the version, build date, and architecture.
3216 conky_build_date string
3218 A string containing the build date for this particular instance
3219 of Conky.
3220 conky_build_arch string
3222 A string containing the build architecture for this particular
3223 instance of Conky.
3224 conky_version string
3226 A string containing the version of the current instance of
3227 Conky.
3228 conky_config string
3230 A string containing the path of the current Conky configuration
3231 file.
3232 cairo_text_extents_t:create() function
3234 Call this function to return a new cairo_text_extents_t struc‐
3235 ture. A creation function for this structure is not provided by
3236 the cairo API. After calling this, you should use tolua.takeown‐
3237 ership() on the return value to ensure ownership is passed prop‐
3238 erly.
3239 cairo_font_extents_t:create() function
3241 Call this function to return a new cairo_font_extents_t struc‐
3242 ture. A creation function for this structure is not provided by
3243 the cairo API. After calling this, you should use tolua.takeown‐
3244 ership() on the return value to ensure ownership is passed prop‐
3245 erly.
3246 cairo_matrix_t:create() function
3248 Call this function to return a new cairo_matrix_t structure. A
3249 creation function for this structure is not provided by the
3250 cairo API. After calling this, you should use tolua.takeowner‐
3251 ship() on the return value to ensure ownership is passed proper‐
3252 ly.
3253 cairo_text_extents_t:destroy(structure) function
3255 Call this function to free memory allocated by cairo_text_ex‐
3256 tents_t:create.
3257 cairo_font_extents_t:destroy(structure) function
3259 Call this function to free memory allocated by cairo_font_ex‐
3260 tents_t:create.
3261 cairo_matrix_t:destroy(structure) function
3263 Call this function to free memory allocated by cairo_ma‐
3264 trix_t:create.
3265
3267 conky -t '${time %D %H:%M}' -o -u 30
3268 Start Conky in its own window with date and clock as text and 30
3269 sec update interval.
3270 conky -a top_left -x 5 -y 500 -d
3272 Start Conky to background at coordinates (5, 500).
3273 conky -C > ~/.config/conky/conky.conf
3275 Do not start Conky, but have it output the builtin default con‐
3276 fig file to ~/.config/conky/conky.conf for later customising.
3277
3279 ${sysconfdir}/conky/conky.conf
3280 Default system-wide configuration file. The value of
3281 ${sysconfdir} depends on the compile-time options (most likely
3282 /etc).
3283 ~/.config/conky/conky.conf
3285 Default personal configuration file.
3286
3288 Drawing to root or some other desktop window directly doesn't work with
3289 all window managers. Especially doesn't work well with Gnome and it has
3290 been reported that it doesn't work with KDE either. Nautilus can be
3291 disabled from drawing to desktop with program gconf-editor. Uncheck
3292 show_desktop in /apps/nautilus/preferences/. There is -w switch in
3293 Conky to set some specific window id. You might find xwininfo -tree
3294 useful to find the window to draw to. You can also use -o argument
3295 which makes Conky to create its own window. If you do try running Conky
3296 in its own window, be sure to read up on the own_window_type settings
3297 and experiment.
3298
3300 https://github.com/brndnmtthws/conky
3301 #conky on irc.freenode.net
3303
3305 Copyright (c) 2005-2019 Brenden Matthews, Philip Kovacs, et. al. Any
3306 original torsmo code is licensed under the BSD license (see LICENSE.BSD
3307 for a copy). All code written since the fork of torsmo is licensed un‐
3308 der the GPL (see LICENSE.GPL for a copy), except where noted different‐
3309 ly (such as in portmon and audacious code which are LGPL, and prss
3310 which is an MIT-style license).
3311
3313 The Conky dev team (see AUTHORS for a full list of contributors).
3314 2012-05-03 conky(1)