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