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 transpar‐
598 ency. 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 intel_backlight
1744 Display the brightness of your Intel backlight in percent.
1745 ioscheduler disk
1748 Prints the current ioscheduler used for the given disk name
1749 (i.e. e.g. "hda" or "sdb").
1750 journal lines (type)
1753 Displays last N lines of the systemd journal. The optional type
1754 can be 'user' or 'system' which will show only the user or sys‐
1755 tem journal respectively. By default, all journal lines visible
1756 to the user are shown. A maximum of 200 lines can be displayed,
1757 or until the text buffer is filled.
1758 kernel Kernel version.
1761 key_caps_lock
1764 An indicator for Capital Lock key.
1765 key_num_lock
1768 An indicator for Number Lock key.
1769 key_scroll_lock
1772 An indicator for Scrolling Lock key.
1773 keyboard_layout
1776 Display keyboard layout.
1777 version
1780 Git version number. DragonFly only.
1781 laptop_mode
1784 The value of /proc/sys/vm/laptop_mode.
1785 lines textfile
1788 Displays the number of lines in the given file.
1789 loadavg (1|2|3)
1792 System load average, 1 is for past 1 minute, 2 for past 5 min‐
1793 utes and 3 for past 15 minutes. Without argument, prints all
1794 three values separated by whitespace.
1795 loadgraph (height),(width) (gradient colour 1) (gradient colour 2)
1798 (scale) (-t) (-l)
1799 Load1 average graph, similar to xload, with optional colours in
1800 hex, minus the #. Uses a logarithmic scale (to see small num‐
1801 bers) when you use the -l switch. Takes the switch '-t' to use a
1802 temperature gradient, which makes the gradient values change de‐
1803 pending on the amplitude of a particular graph value (try it and
1804 see).
1805 lua function_name (function parameters)
1808 Executes a Lua function with given parameters, then prints the
1809 returned string. See also 'lua_load' on how to load scripts.
1810 Conky puts 'conky_' in front of function_name to prevent acci‐
1811 dental calls to the wrong function unless you put you place
1812 'conky_' in front of it yourself.
1813 lua_bar (height, width) function_name (function parameters)
1816 Executes a Lua function with given parameters and draws a bar.
1817 Expects result value to be an integer between 0 and 100. See al‐
1818 so 'lua_load' on how to load scripts. Conky puts 'conky_' in
1819 front of function_name to prevent accidental calls to the wrong
1820 function unless you put you place 'conky_' in front of it your‐
1821 self.
1822 lua_gauge (height, width) function_name (function parameters)
1825 Executes a Lua function with given parameters and draws a gauge.
1826 Expects result value to be an integer between 0 and 100. See al‐
1827 so 'lua_load' on how to load scripts. Conky puts 'conky_' in
1828 front of function_name to prevent accidental calls to the wrong
1829 function unless you put you place 'conky_' in front of it your‐
1830 self.
1831 lua_graph function_name (height),(width) (gradient colour 1) (gradient
1834 colour 2) (scale) (-t) (-l)
1835 Executes a Lua function with and draws a graph. Expects result
1836 value to be any number, and by default will scale to show the
1837 full range. See also 'lua_load' on how to load scripts. Takes
1838 the switch '-t' to use a temperature gradient, which makes the
1839 gradient values change depending on the amplitude of a particu‐
1840 lar graph value (try it and see). Conky puts 'conky_' in front
1841 of function_name to prevent accidental calls to the wrong func‐
1842 tion unless you put you place 'conky_' in front of it yourself.
1843 lua_parse function_name (function parameters)
1846 Executes a Lua function with given parameters as per $lua, then
1847 parses and prints the result value as per the syntax for the
1848 conky.text section. See also 'lua_load' on how to load scripts.
1849 Conky puts 'conky_' in front of function_name to prevent acci‐
1850 dental calls to the wrong function unless you put you place
1851 'conky_' in front of it yourself.
1852 machine
1855 Machine, e.g. i686, x86_64.
1856 mails (mailbox) (interval)
1859 Mail count in the specified mailbox or your mail spool if not.
1860 Both mbox and maildir type mailboxes are supported. You can use
1861 a program like fetchmail to get mails from some server using
1862 your favourite protocol. See also new_mails.
1863 mboxscan (-n number of messages to print) (-fw from width) (-sw subject
1866 width) mbox
1867 Print a summary of recent messages in an mbox format mailbox.
1868 mbox parameter is the filename of the mailbox (can be encapsu‐
1869 lated using '"', ie. ${mboxscan -n 10 "/home/brenden/some box"}
1870 mem Amount of memory in use.
1873 memwithbuffers
1876 Amount of memory in use, including that used by system buffers
1877 and caches.
1878 membar (height),(width)
1881 Bar that shows amount of memory in use.
1882 memwithbuffersbar (height),(width)
1885 Bar that shows amount of memory in use (including memory used by
1886 system buffers and caches).
1887 memwithbuffersgraph (height),(width) (gradient colour 1) (gradient
1890 colour 2) (scale) (-t) (-l)
1891 Memory usage graph including memory used by system buffers and
1892 cache. Uses a logarithmic scale (to see small numbers) when you
1893 use the -l switch. Takes the switch '-t' to use a temperature
1894 gradient, which makes the gradient values change depending on
1895 the amplitude of a particular graph value (try it and see).
1896 memdirty
1899 Amount of "dirty" memory. Linux only.
1900 memeasyfree
1903 Amount of free memory including the memory that is very easily
1904 freed (buffers/cache).
1905 memfree
1908 Amount of free memory.
1909 legacymem
1912 Amount of memory used, calculated the same way as in the `free`
1913 program.
1914 memgauge (height),(width)
1917 Gauge that shows amount of memory in use (see cpugauge).
1918 memgraph (height),(width) (gradient colour 1) (gradient colour 2)
1921 (scale) (-t) (-l)
1922 Memory usage graph. Uses a logarithmic scale (to see small num‐
1923 bers) when you use the -l switch. Takes the switch '-t' to use a
1924 temperature gradient, which makes the gradient values change de‐
1925 pending on the amplitude of a particular graph value (try it and
1926 see).
1927 memmax Total amount of memory.
1930 memperc
1933 Percentage of memory in use.
1934 mixer (device)
1937 Prints the mixer value as reported by the OS. On Linux, this
1938 variable uses the OSS emulation, so you need the proper kernel
1939 module loaded. Default mixer is "Vol", but you can specify one
1940 of the available OSS controls: "Vol", "Bass", "Trebl", "Synth",
1941 "Pcm", "Spkr", "Line", "Mic", "CD", "Mix", "Pcm2 ", "Rec",
1942 "IGain", "OGain", "Line1", "Line2", "Line3", "Digital1", "Digi‐
1943 tal2", "Digital3", "PhoneIn", "PhoneOut", "Video", "Radio" and
1944 "Monitor".
1945 mixerbar (device)
1948 Displays mixer value in a bar as reported by the OS. See docs
1949 for $mixer for details on arguments.
1950 mixerl (device)
1953 Prints the left channel mixer value as reported by the OS. See
1954 docs for $mixer for details on arguments.
1955 mixerlbar (device)
1958 Displays the left channel mixer value in a bar as reported by
1959 the OS. See docs for $mixer for details on arguments.
1960 mixerr (device)
1963 Prints the right channel mixer value as reported by the OS. See
1964 docs for $mixer for details on arguments.
1965 mixerrbar (device)
1968 Displays the right channel mixer value in a bar as reported by
1969 the OS. See docs for $mixer for details on arguments.
1970 moc_album
1973 Album of the current MOC song.
1974 moc_artist
1977 Artist of the current MOC song.
1978 moc_bitrate
1981 Bitrate in the current MOC song.
1982 moc_curtime
1985 Current time of the current MOC song.
1986 moc_file
1989 File name of the current MOC song.
1990 moc_rate
1993 Rate of the current MOC song.
1994 moc_song
1997 The current song name being played in MOC.
1998 moc_state
2001 Current state of MOC; playing, stopped etc.
2002 moc_timeleft
2005 Time left in the current MOC song.
2006 moc_title
2009 Title of the current MOC song.
2010 moc_totaltime
2013 Total length of the current MOC song.
2014 monitor
2017 Number of the monitor on which conky is running or the message
2018 "Not running in X" if this is the case.
2019 monitor_number
2022 Number of monitors or the message "Not running in X" if this is
2023 the case.
2024 mouse_speed
2027 Display mouse speed.
2028 mpd_album
2031 Album in current MPD song.
2032 mpd_artist
2035 Artist in current MPD song must be enabled at compile.
2036 mpd_albumartist
2039 Artist of the album of the current MPD song.
2040 mpd_bar (height),(width)
2043 Bar of mpd's progress.
2044 mpd_bitrate
2047 Bitrate of current song.
2048 mpd_date
2051 Date of current song.
2052 mpd_elapsed
2055 Song's elapsed time.
2056 mpd_file
2059 Prints the file name of the current MPD song.
2060 mpd_length
2063 Song's length.
2064 mpd_name
2067 Prints the MPD name field.
2068 mpd_percent
2071 Percent of song's progress.
2072 mpd_random
2075 Random status (On/Off).
2076 mpd_repeat
2079 Repeat status (On/Off).
2080 mpd_smart (max length)
2083 Prints the song name in either the form "artist - title" or file
2084 name, depending on whats available.
2085 mpd_status
2088 Playing, stopped, et cetera.
2089 mpd_title (max length)
2092 Title of current MPD song.
2093 mpd_comment (max length)
2096 Comment of current MPD song.
2097 mpd_track
2100 Prints the MPD track field.
2101 mpd_vol
2104 MPD's volume.
2105 mysql query
2108 Shows the first field of the first row of the result of the
2109 query.
2110 nameserver (index)
2113 Print a nameserver from /etc/resolv.conf. Index starts at and
2114 defaults to 0.
2115 new_mails (mailbox) (interval)
2118 Unread mail count in the specified mailbox or mail spool if not.
2119 Both mbox and maildir type mailboxes are supported.
2120 nodename
2123 Hostname.
2124 nodename_short
2127 Short hostname (same as 'hostname -s' shell command).
2128 no_update text
2131 Shows text and parses the vars in it, but doesn't update them.
2132 Use this for things that do not change while conky is running,
2133 like $machine, $conky_version,... By not updating this you can
2134 save some resources.
2135 nvidia argument (GPU_ID)
2138 Nvidia graphics card information via the XNVCtrl library.
2139 GPU_ID:Optional parameter to choose the GPU to be used as
2141 0,1,2,3,.. Default parameter is 0
2142 Possible arguments:(Temperatures are printed as float, all other
2144 values as integer. Bracketed arguments are aliases)
2145 gputemp( temp) GPU temperature
2147 gputempthreshold( threshold) Temperature threshold where the GPU
2148 will reduce it's clock speed
2149 ambienttemp( ambient) Ambient temperature outside the graphics
2150 card
2151 gpufreqcur( gpufreq) Current GPU clock speed
2152 gpufreqmin Minimum GPU clock speed
2153 gpufreqmax Maximum GPU clock speed
2154 memfreqcur( memfreq) Current memory clock speed
2155 memfreqmin Minimum memory clock speed
2156 memfreqmax Maximum memory clock speed
2157 mtrfreqcur( mtrfreq) Current memory transfer rate clock speed
2158 mtrfreqmin Minimum memory transfer rate clock speed
2159 mtrfreqmax Maximum memory transfer rate clock speed
2160 perflevelcur( perflevel) Current performance level
2161 perflevelmin Lowest performance level
2162 perflevelmax Highest performance level
2163 perfmode Performance mode
2164 gpuutil GPU utilization %
2165 membwutil Memory bandwidth utilization %
2166 videoutil Video engine utilization %
2167 pcieutil PCIe bandwidth utilization %
2168 memused( mem) Amount of used memory
2169 memfree( memavail) Amount of free memory
2170 memmax( memtotal) Total amount of memory
2171 memutil( memperc) Memory utilization %
2172 fanspeed Fan speed
2173 fanlevel Fan level %
2174 imagequality Image quality
2175 modelname name of the GPU card
2176 driverversion Driver version
2177 nvidiabar (height),(width) argument (GPU_ID)
2179 Same as nvidia, except it draws its output in a horizontal bar.
2180 The height and width parameters are optional, and default to the
2181 default_bar_height and default_bar_width config settings, re‐
2182 spectively.
2183 GPU_ID:Optional parameter to choose the GPU to be used as
2185 0,1,2,3,.. Default parameter is 0
2186 Note the following arguments are incompatible: gputempthreshold(
2188 threshold)
2189 gpufreqmin
2190 gpufreqmax
2191 memfreqmin
2192 memfreqmax
2193 mtrfreqmin
2194 mtrfreqmax
2195 perflevelmin
2196 perflevelmax
2197 perfmode
2198 memtotal( memmax)
2199 fanspeed
2200 nvidiagauge (height),(width) argument (GPU_ID)
2202 Same as nvidiabar, except a round gauge (much like a vehicle
2203 speedometer). The height and width parameters are optional, and
2204 default to the default_gauge_height and default_gauge_width con‐
2205 fig settings, respectively.
2206 GPU_ID:Optional parameter to choose the GPU to be used as
2208 0,1,2,3,.. Default parameter is 0
2209 For possible arguments see nvidia and nvidiabar.
2211 nvidiagraph argument (height),(width) (gradient color 1) (gradient col‐
2213 or 2) (scale) (-t) (-l) GPU_ID
2214 Same as nvidiabar, except a horizontally scrolling graph with
2215 values from 0-100 plotted on the vertical axis. The height and
2216 width parameters are optional, and default to the de‐
2217 fault_graph_height and default_graph_width config settings, re‐
2218 spectively.
2219 GPU_ID:NOT optional. This parameter allows to choose the GPU to
2221 be used as 0,1,2,3,..
2222 For possible arguments see nvidia and nvidiabar. To learn more
2224 about the -t -l and gradient color options, see execgraph.
2225 offset (pixels)
2227 Move text over by N pixels. See also $voffset.
2228 outlinecolor (color)
2231 Change outline color.
2232 password (length)
2235 Generate random passwords.
2236 pa_sink_volume
2239 Pulseaudio's default sink volume percentage.
2240 pa_sink_volumebar
2243 Pulseaudio's default sink volume bar.
2244 pa_sink_description
2247 Pulseaudio's default sink description.
2248 pa_sink_active_port_name
2251 Pulseaudio's default sink active port name.
2252 pa_sink_active_port_description
2255 Pulseaudio's default sink active port description.
2256 pa_card_name
2259 Pulseaudio's default card name.
2260 pa_card_active_profile
2263 Pulseaudio's default card active profile.
2264 pb_battery item
2267 If running on Apple powerbook/ibook, display information on bat‐
2268 tery status. The item parameter specifies, what information to
2269 display. Exactly one item must be specified. Valid items are:
2270 status Display if battery is fully charged, charging, discharg‐
2272 ing or absent (running on AC)
2273 percent Display charge of battery in percent, if charging or
2274 discharging. Nothing will be displayed, if battery is fully
2275 charged or absent.
2276 time Display the time remaining until the battery will be fully
2277 charged or discharged at current rate. Nothing is displayed, if
2278 battery is absent or if it's present but fully charged and not
2279 discharging.
2280 pid_chroot pid
2283 Directory used as rootdirectory by the process (this will be "/"
2284 unless the process did a chroot syscall).
2285 pid_cmdline pid
2288 Command line this process was invoked with.
2289 pid_cwd pid
2292 Current working directory of the process.
2293 pid_environ pid varname
2296 Contents of a environment-var of the process.
2297 pid_environ_list pid
2300 List of environment-vars that the process can see.
2301 pid_exe pid
2304 Path to executed command that started the process.
2305 pid_nice pid
2308 The nice value of the process.
2309 pid_openfiles pid
2312 List of files that the process has open.
2313 pid_parent pid
2316 The pid of the parent of the process.
2317 pid_priority pid
2320 The priority of the process (see 'priority' in "man 5 proc").
2321 pid_read pid
2324 Total number of bytes read by the process.
2325 pid_state pid
2328 State of the process.
2329 pid_state_short pid
2332 One of the chars in "RSDZTW" representing the state of the
2333 process where R is running, S is sleeping in an interruptible
2334 wait, D is waiting in uninterruptible disk sleep, Z is zombie, T
2335 is traced or stopped (on a signal), and W is paging.
2336 pid_stderr pid
2339 Filedescriptor binded to the STDERR of the process.
2340 pid_stdin pid
2343 Filedescriptor binded to the STDIN of the process.
2344 pid_stdout pid
2347 Filedescriptor binded to the STDOUT of the process.
2348 pid_threads pid
2351 Number of threads in process containing this thread.
2352 pid_thread_list pid
2355 List with pid's from threads from this process.
2356 pid_time_kernelmode pid
2359 Amount of time that the process has been scheduled in kernel
2360 mode in seconds.
2361 pid_time_usermode pid
2364 Amount of time that the process has been scheduled in user mode
2365 in seconds.
2366 pid_time pid
2369 Sum of $pid_time_kernelmode and $pid_time_usermode.
2370 pid_uid pid
2373 The real uid of the process.
2374 pid_euid pid
2377 The effective uid of the process.
2378 pid_suid pid
2381 The saved set uid of the process.
2382 pid_fsuid pid
2385 The file system uid of the process.
2386 pid_gid pid
2389 The real gid of the process.
2390 pid_egid pid
2393 The effective gid of the process.
2394 pid_sgid pid
2397 The saved set gid of the process.
2398 pid_fsgid pid
2401 The file system gid of the process.
2402 pid_vmpeak pid
2405 Peak virtual memory size of the process.
2406 pid_vmsize pid
2409 Virtual memory size of the process.
2410 pid_vmlck pid
2413 Locked memory size of the process.
2414 pid_vmhwm pid
2417 Peak resident set size ("high water mark") of the process.
2418 pid_vmrss pid
2421 Resident set size of the process.
2422 pid_vmdata pid
2425 Data segment size of the process.
2426 pid_vmstk pid
2429 Stack segment size of the process.
2430 pid_vmexe pid
2433 Text segment size of the process.
2434 pid_vmlib pid
2437 Shared library code size of the process.
2438 pid_vmpte pid
2441 Page table entries size of the process.
2442 pid_write pid
2445 Total number of bytes written by the process.
2446 platform (dev) type n (factor offset)
2449 Platform sensor from sysfs (Linux 2.6). Parameter dev may be
2450 omitted if you have only one platform device. Platform type is
2451 either 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp'
2452 meaning temperature. Parameter n is number of the sensor. See
2453 /sys/bus/platform/devices/ on your local computer. The optional
2454 arguments 'factor' and 'offset' allow precalculation of the raw
2455 input, which is being modified as follows: 'input = input * fac‐
2456 tor + offset'. Note that they have to be given as decimal values
2457 (i.e. contain at least one decimal place).
2458 pop3_unseen (args)
2461 Displays the number of unseen messages in your global POP3 inbox
2462 by default. You can define individual POP3 inboxes separately by
2463 passing arguments to this object. Arguments are: "host user pass
2464 [-i interval (in seconds)] [-p port] [-e 'command'] [-r re‐
2465 tries]". Default port is 110, default interval is 5 minutes, and
2466 default number of retries before giving up is 5. If the password
2467 is supplied as '*', you will be prompted to enter the password
2468 when Conky starts.
2469 pop3_used (args)
2472 Displays the amount of space (in MiB, 2^20) used in your global
2473 POP3 inbox by default. You can define individual POP3 inboxes
2474 separately by passing arguments to this object. Arguments are:
2475 "host user pass [-i interval (in seconds)] [-p port] [-e 'com‐
2476 mand'] [-r retries]". Default port is 110, default interval is 5
2477 minutes, and default number of retries before giving up is 5. If
2478 the password is supplied as '*', you will be prompted to enter
2479 the password when Conky starts.
2480 processes
2483 Total processes (sleeping and running).
2484 read_tcp (host) port
2487 Connects to a tcp port on a host (default is localhost), reads
2488 every char available at the moment and shows them.
2489 read_udp (host) port
2492 Connects to a udp port on a host (default is localhost), reads
2493 every char available at the moment and shows them.
2494 replied_mails (maildir) (interval)
2497 Number of mails marked as replied in the specified mailbox or
2498 mail spool if not. Only maildir type mailboxes are supported,
2499 mbox type will return -1.
2500 rss uri interval_in_seconds action (num_par (spaces_in_front))
2503 Download and parse RSS feeds. The interval may be a (floating
2504 point) value greater than 0. Action may be one of the following:
2505 feed_title, item_title (with num par), item_desc (with num par)
2506 and item_titles (when using this action and spaces_in_front is
2507 given conky places that many spaces in front of each item). This
2508 object is threaded, and once a thread is created it can't be ex‐
2509 plicitly destroyed. One thread will run for each URI specified.
2510 You can use any protocol that Curl supports.
2511 running_processes
2514 Running processes (not sleeping). Requires Linux 2.6.
2515 running_threads
2518 Number of running (runnable) threads. Linux only.
2519 scroll (direction) length (step) (interval) text
2522 Scroll 'text' by 'step' characters to the left or right (set
2523 'direction' to 'left' or 'right' or 'wait') showing 'length'
2524 number of characters at the same time. The text may also contain
2525 variables. 'step' is optional and defaults to 1 if not set.
2526 'direction' is optional and defaults to left if not set. When
2527 direction is 'wait' then text will scroll left and wait for 'in‐
2528 terval' itertations at the beginning and end of the text. If a
2529 var creates output on multiple lines then the lines are placed
2530 behind each other separated with a '|'-sign. If you change the
2531 textcolor inside $scroll it will automatically have it's old
2532 value back at the end of $scroll. The end and the start of text
2533 will be separated by 'length' number of spaces unless direction
2534 is 'wait'.
2535 seen_mails (maildir) (interval)
2538 Number of mails marked as seen in the specified mailbox or mail
2539 spool if not. Only maildir type mailboxes are supported, mbox
2540 type will return -1.
2541 sip_status (switch)
2544 Prints info regarding System Integrity Protection (SIP) on mac‐
2545 OS. If no switch is provided, prints SIP status (enabled / dis‐
2546 abled), else, status of the specific SIP feature corresponding
2547 to the switch provided. Below are shown the available switches:
2548 SWITCH--------------------------RE‐
2549 SULT--------------------------STATUS 0 apple internal YES/NO 1
2550 forbid untrusted kexts YES/NO 2 forbid task-for-pid YES/NO 3 re‐
2551 strict filesystem YES/NO 4 forbid kernel-debugger YES/NO 5 re‐
2552 strict dtrace YES/NO 6 restrict nvram YES/NO 7 forbid device-
2553 configuration YES/NO 8 forbid any-recovery-os YES/NO 9 forbid
2554 user-approved-kexts YES/NO a uses unsupported configuration? (*)
2555 (*): If yes, prints "unsupported configuration, beware!" Else,
2556 prints "configuration is ok".
2557 ----------------------------------------------------------------------
2558 USAGE: conky -t '${sip_status}' # print SIP status conky -t
2559 '${sip_status 0}' # print allows apple-internal? Yes or No?
2560 NOTES: * Available for all macOS versions (even the ones prior
2561 El Capitan where SIP was first introduced) * If run on versions
2562 prior El Capitan SIP is unavailable, so all you will get is "un‐
2563 supported".
2564 shadecolor (color)
2567 Change shading color.
2568 smapi (ARGS)
2571 when using smapi, display contents of the /sys/devices/plat‐
2572 form/smapi directory. ARGS are either '(FILENAME)' or 'bat (IN‐
2573 DEX) (FILENAME)' to display the corresponding files' content.
2574 This is a very raw method of accessing the smapi values. When
2575 available, better use one of the smapi_* variables instead.
2576 smapi_bat_bar (INDEX),(height),(width)
2579 when using smapi, display the remaining capacity of the battery
2580 with index INDEX as a bar.
2581 smapi_bat_perc (INDEX)
2584 when using smapi, display the remaining capacity in percent of
2585 the battery with index INDEX. This is a separate variable be‐
2586 cause it supports the 'use_spacer' configuration option.
2587 smapi_bat_power INDEX
2590 when using smapi, display the current power of the battery with
2591 index INDEX in watt. This is a separate variable because the
2592 original read out value is being converted from mW. The sign of
2593 the output reflects charging (positive) or discharging (nega‐
2594 tive) state.
2595 smapi_bat_temp INDEX
2598 when using smapi, display the current temperature of the battery
2599 with index INDEX in degree Celsius. This is a separate variable
2600 because the original read out value is being converted from mil‐
2601 li degree Celsius.
2602 sony_fanspeed
2605 Displays the Sony VAIO fanspeed information if sony-laptop ker‐
2606 nel support is enabled. Linux only.
2607 startcase text
2610 Capitalises the start of each word.
2611 lowercase text
2614 Converts all letters into lowercase.
2615 uppercase text
2618 Converts all letters into uppercase.
2619 rstrip text
2622 Strips all trailing whitespace from input.
2623 stippled_hr (space)
2626 Stippled (dashed) horizontal line.
2627 stock symbol data
2630 Displays the data of a stock symbol. The following data is sup‐
2631 ported: adv(Average Daily Volume), ask, asksize, bid, askrt(ask
2632 realtime), bidrt(bid realtime), bookvalue, bidsize, change, com‐
2633 mission, changert(change realtime), ahcrt(After Hours Change re‐
2634 altime), ds(dividend/share), ltd(Last Trade Date), tradedate,
2635 es(earnings/share), ei(error indication), epsecy(EPS Estimate
2636 Current Year), epseny(EPS Estimate Next Year), epsenq(EPS Esti‐
2637 mate Next Quarter), floatshares, dayslow, dayshigh, 52weeklow,
2638 52weekhigh, hgp(Holdings Gain Percent), ag(Annualized Gain),
2639 hg(Holdings Gain), hgprt(Holdings Gain Percent realtime),
2640 hgrt(Holdings Gain realtime), moreinfo, obrt(Order Book real‐
2641 time), mc(Market Capitalization), mcrt(Market Cap realtime),
2642 ebitda, c52wlow(Change From 52-week Low), pc52wlow(Percent
2643 Change From 52-week Low), cprt(change percent realtime),
2644 lts(Last Trade Size), c52whigh(Change from 52-week high),
2645 pc52whigh(percent change from 52-week high), ltp(last trade
2646 price), hl(high limit), ll(low limit), dr(day's range), dr‐
2647 rt(day's range realtime), 50ma(50-day Moving Average),
2648 200ma(200-day Moving Average), c200ma(Change From 200-day Moving
2649 Average), pc200ma(Percent Change From 200-day Moving Average),
2650 c50ma(Change From 50-day Moving Average), pc50ma(Percent Change
2651 From 50-day Moving Average), name, notes, open, pc(previous
2652 close), pricepaid, cip(change in percent), ps(price/sales),
2653 pb(price/book), edv(Ex-Dividend Date), per(P/E Ratio), dpd(Divi‐
2654 dend Pay Date), perrt(P/E Ratio realtime), pegr(PEG Ratio),
2655 pepsecy(Price/EPS Estimate Current Year), pepseny(Price/EPS Es‐
2656 timate Next Year), symbol, sharesowned, shortratio, ltt(Last
2657 Trade Time), tradelinks, tt(Ticker Trend), 1ytp(1 yr Target
2658 Price), volume, hv(Holdings Value), hvrt(Holdings Value real‐
2659 time), 52weekrange, dvc(Day's Value Change), dvcrt(Day's Value
2660 Change realtime), se(Stock Exchange), dy(Dividend Yield).
2661 swap Amount of swap in use.
2664 swapbar (height),(width)
2667 Bar that shows amount of swap in use.
2668 swapfree
2671 Amount of free swap.
2672 swapmax
2675 Total amount of swap.
2676 swapperc
2679 Percentage of swap in use.
2680 sysname
2683 System name, e.g. Linux.
2684 sysctlbyname (name)
2687 Print sysctl value by name. FreeBSD only.
2688 tab (width, (start))
2691 Puts a tab of the specified width, starting from column 'start'.
2692 The unit is pixels for both arguments.
2693 tail logfile lines (next_check)
2696 Displays last N lines of supplied text file. The file is checked
2697 every 'next_check' update. If next_check is not supplied, Conky
2698 defaults to 2. Max of 30 lines can be displayed, or until the
2699 text buffer is filled.
2700 tcp_ping host (port)
2703 Displays the number of microseconds it takes to get a reply on a
2704 ping to to tcp 'port' on 'host'. 'port' is optional and has 80
2705 as default. This works on both open and closed ports, just make
2706 sure that the port is not behind a firewall or you will get
2707 'down' as answer. It's best to test a closed port instead of an
2708 open port, you will get a quicker response.
2709 tcp_portmon port_begin port_end item (index)
2712 TCP port (both IPv6 and IPv4) monitor for specified local ports.
2713 Port numbers must be in the range 1 to 65535. Valid items are:
2714 count Total number of connections in the range
2716 rip Remote ip address
2717 rhost Remote host name
2718 rport Remote port number
2719 rservice Remote service name from /etc/services
2720 lip Local ip address
2721 lhost Local host name
2722 lport Local port number
2723 lservice Local service name from /etc/services
2724 The connection index provides you with access to each connection
2726 in the port monitor. The monitor will return information for in‐
2727 dex values from 0 to n-1 connections. Values higher than n-1 are
2728 simply ignored. For the "count" item, the connection index must
2729 be omitted. It is required for all other items.
2730 Examples:
2732 ${tcp_portmon 6881 6999 count} Displays the number of connec‐
2734 tions in the bittorrent port range
2735 ${tcp_portmon 22 22 rip 0} Displays the remote host ip of the
2736 first sshd connection
2737 ${tcp_portmon 22 22 rip 9} Displays the remote host ip of the
2738 tenth sshd connection
2739 ${tcp_portmon 1 1024 rhost 0} Displays the remote host name of
2740 the first connection on a privileged port
2741 ${tcp_portmon 1 1024 rport 4} Displays the remote host port of
2742 the fifth connection on a privileged port
2743 ${tcp_portmon 1 65535 lservice 14} Displays the local service
2744 name of the fifteenth connection in the range of all ports
2745 Note that port monitor variables which share the same port range
2747 actually refer to the same monitor, so many references to a sin‐
2748 gle port range for different items and different indexes all use
2749 the same monitor internally. In other words, the program avoids
2750 creating redundant monitors.
2751 templateN (arg1) (arg2) (arg3 ...)
2753 Evaluate the content of the templateN configuration variable
2754 (where N is a value between 0 and 9, inclusively), applying sub‐
2755 stitutions as described in the documentation of the correspond‐
2756 ing configuration variable. The number of arguments is optional,
2757 but must match the highest referred index in the template. You
2758 can use the same special sequences in each argument as the ones
2759 valid for a template definition, e.g. to allow an argument to
2760 contain a whitespace. Also simple nesting of templates is possi‐
2761 ble this way.
2762 Here are some examples of template definitions, note they are
2764 placed between [[ ... ]] instead of ' ... ':
2765 template0 = [[$\1\2]]
2767 template1 = [[\1: ${fs_used \2} / ${fs_size \2}]]
2768 template2 = [[\1 \2]]
2769 The following list shows sample usage of the templates defined
2771 above, with the equivalent syntax when not using any template at
2772 all:
2773 using template same without template
2776 ────────────────────────────────────────────────────────
2777 ${template0 node name} $nodename
2778 ${template1 root /} root: ${fs_free /} /
2779 ${fs_size /}
2780 ${template1 ${template2\ disk root: ${fs_free /} /
2781 disk\ root} /} ${fs_size /}
2782 texeci interval command
2784 Runs a command at an interval inside a thread and displays the
2785 output. Same as $execi, except the command is run inside a
2786 thread. Use this if you have a slow script to keep Conky updat‐
2787 ing. You should make the interval slightly longer than the time
2788 it takes your script to execute. For example, if you have a
2789 script that take 5 seconds to execute, you should make the in‐
2790 terval at least 6 seconds. See also $execi. This object will
2791 clean up the thread when it is destroyed, so it can safely be
2792 used in a nested fashion, though it may not produce the desired
2793 behaviour if used this way.
2794 texecpi interval command
2797 Same as execpi, except the command is run inside a thread.
2798 threads
2801 Total threads.
2802 time (format)
2805 Local time, see "man strftime" to get more information about
2806 format.
2807 to_bytes size
2810 If 'size' is a number followed by a size-unit (kilo‐
2811 byte,mb,GiB,...) then it converts the size to bytes and shows it
2812 without unit, otherwise it just shows 'size'.
2813 top type num
2816 This takes arguments in the form:top (name) (number) Basically,
2817 processes are ranked from highest to lowest in terms of cpu us‐
2818 age, which is what (num) represents. The types are: "name",
2819 "pid", "cpu", "mem", "mem_res", "mem_vsize", "time", "uid", "us‐
2820 er", "io_perc", "io_read" and "io_write". There can be a max of
2821 10 processes listed.
2822 top_io type num
2825 Same as top, except sorted by the amount of I/O the process has
2826 done during the update interval.
2827 top_mem type num
2830 Same as top, except sorted by mem usage instead of cpu.
2831 top_time type num
2834 Same as top, except sorted by total CPU time instead of current
2835 CPU usage.
2836 totaldown (net)
2839 Total download, overflows at 4 GB on Linux with 32-bit arch and
2840 there doesn't seem to be a way to know how many times it has al‐
2841 ready done that before conky has started.
2842 totalup (net)
2845 Total upload, this one too, may overflow.
2846 trashed_mails (maildir) (interval)
2849 Number of mails marked as trashed in the specified mailbox or
2850 mail spool if not. Only maildir type mailboxes are supported,
2851 mbox type will return -1.
2852 tztime (timezone (format))
2855 Local time for specified timezone, see man strftime to get more
2856 information about format. The timezone argument is specified in
2857 similar fashion as TZ environment variable. For hints, look in
2858 /usr/share/zoneinfo. e.g. US/Pacific, Europe/Zurich, etc.
2859 gid_name gid
2862 Name of group with this gid.
2863 uid_name uid
2866 Username of user with this uid.
2867 unflagged_mails (maildir) (interval)
2870 Number of mails not marked as flagged in the specified mailbox
2871 or mail spool if not. Only maildir type mailboxes are supported,
2872 mbox type will return -1.
2873 unforwarded_mails (maildir) (interval)
2876 Number of mails not marked as forwarded in the specified mailbox
2877 or mail spool if not. Only maildir type mailboxes are supported,
2878 mbox type will return -1.
2879 unreplied_mails (maildir) (interval)
2882 Number of mails not marked as replied in the specified mailbox
2883 or mail spool if not. Only maildir type mailboxes are supported,
2884 mbox type will return -1.
2885 unseen_mails (maildir) (interval)
2888 Number of new or unseen mails in the specified mailbox or mail
2889 spool if not. Only maildir type mailboxes are supported, mbox
2890 type will return -1.
2891 updates Number of updates
2894 for debugging.
2895 upspeed (net)
2898 Upload speed in suitable IEC units.
2899 upspeedf (net)
2902 Upload speed in KiB with one decimal.
2903 upspeedgraph (netdev) (height),(width) (gradient colour 1) (gradient
2906 colour 2) (scale) (-t) (-l)
2907 Upload speed graph, colours defined in hex, minus the #. If
2908 scale is non-zero, it becomes the scale for the graph. Uses a
2909 logarithmic scale (to see small numbers) when you use the -l
2910 switch. Takes the switch '-t' to use a temperature gradient,
2911 which makes the gradient values change depending on the ampli‐
2912 tude of a particular graph value (try it and see).
2913 uptime Uptime.
2916 uptime_short
2919 Uptime in a shorter format.
2920 user_names
2923 Lists the names of the users logged in.
2924 user_number
2927 Number of users logged in.
2928 user_terms
2931 Lists the consoles in use.
2932 user_times
2935 Lists how long users have been logged in for.
2936 user_time console
2939 Lists how long the user for the given console has been logged in
2940 for.
2941 utime (format)
2944 Display time in UTC (universal coordinate time).
2945 v6addrs (-n) (-s) (interface)
2948 IPv6 addresses for an interface, followed by netmask if -n is
2949 specified and scope with -s. Scopes are Global(G), Host-lo‐
2950 cal(H), Link-local(L), Site-local(S), Compat(C) and Unspeci‐
2951 fied(/). Linux only.
2952 voffset (pixels)
2955 Change vertical offset by N pixels. Negative values will cause
2956 text to overlap. See also $offset.
2957 voltage_mv (n)
2960 Returns CPU #n's voltage in mV. CPUs are counted from 1. If
2961 omitted, the parameter defaults to 1.
2962 voltage_v (n)
2965 Returns CPU #n's voltage in V. CPUs are counted from 1. If omit‐
2966 ted, the parameter defaults to 1.
2967 weather URI locID data_type (interval_in_minutes)
2970 Download, parse and display METAR data.
2971 'URI' must be a valid METAR URI.
2973 http://tgftp.nws.noaa.gov/data/observations/metar/stations/
2975 'locID' must be a valid location identifier for the required
2977 uri. For the NOAA site this must be a valid ICAO (see for in‐
2978 stance https://pilotweb.nas.faa.gov/qryhtml/icao/). For the
2979 weather.com site this must be a valid location ID (see for in‐
2980 stance http://aspnetresources.com/tools/locid.aspx).
2981 'data_type' must be one of the following:
2983 last_update The date and time stamp of the data. The result de‐
2985 pends on the URI used. For the NOAA site it is date (yyyy/mm/dd)
2986 and UTC time. For the weather.com one it is date ([m]m/[d]d/yy)
2987 and Local Time of the station.
2988 temperature
2989 Air temperature (you can use the 'temperature_unit' config set‐
2991 ting to change units)
2992 cloud_cover
2993 The highest cloud cover status
2995 pressure
2996 Air pressure in millibar
2998 wind_speed
2999 Wind speed in km/h
3001 wind_dir
3002 Wind direction
3004 wind_dir_DEG
3005 Compass wind direction
3007 humidity
3008 Relative humidity in %
3010 weather
3011 Any relevant weather event (rain, snow, etc.). This is not used
3013 if you are querying the weather.com site since this data is ag‐
3014 gregated into the cloud_cover one
3015 icon
3016 Weather icon (only for www.weather.com). Can be used together
3018 with the icon kit provided upon registering to their service.
3019 'delay_in_minutes' (optional, default 30) cannot be less than 30
3021 minutes.
3022 This object is threaded, and once a thread is created it can't
3024 be explicitly destroyed. One thread will run for each URI speci‐
3025 fied.
3026 Note that these variables are still EXPERIMENTAL and can be sub‐
3028 ject to many future changes.
3029 weather_forecast URI locID day data_type (interval_in_minutes)
3031 Download, parse and display weather forecast data for a given
3032 day (daytime only).
3033 'locID', see 'weather' above.
3035 'day' is a number from 0 (today) to 4 (3 days after tomorrow).
3037 'data_type' must be one of the following:
3039 day Day of the week
3041 date Date, in the form MMM DD (ie. Jul 14)
3042 low Minimum temperature (you can use the 'temperature_unit' con‐
3043 fig setting to change units)
3044 hi Maximum temperature (you can use the 'temperature_unit' con‐
3045 fig setting to change units)
3046 icon Weather icon. Can be used together with the icon kit pro‐
3047 vided upon registering to the weather.com service
3048 forecast Weather forecast (sunny, rainy, etc.)
3049 wind_speed Wind speed in km/h
3050 wind_dir Wind direction
3051 wind_dir_DEG Compass wind direction
3052 humidity Relative humidity in %
3053 precipitation Probability of having a precipitation (in %)
3054 'delay_in_minutes' (optional, default 210) cannot be lower than
3056 210 min.
3057 This object is threaded, and once a thread is created it can't
3059 be explicitly destroyed. One thread will run for each URI speci‐
3060 fied. You can use any protocol that Curl supports.
3061 Note that these variables are still EXPERIMENTAL and can be sub‐
3063 ject to many future changes.
3064 wireless_ap (net)
3066 Wireless access point MAC address. Linux only.
3067 wireless_bitrate (net)
3070 Wireless bitrate (ie 11 Mb/s). Linux only.
3071 wireless_channel (net)
3074 WLAN channel on which device 'net' is listening.
3075 wireless_essid (net)
3078 Wireless access point ESSID. Linux only.
3079 wireless_freq (net)
3082 Frequency on which device 'net' is listening.
3083 wireless_link_bar (height),(width) (net)
3086 Wireless link quality bar. Linux only.
3087 wireless_link_qual (net)
3090 Wireless link quality. Linux only.
3091 wireless_link_qual_max (net)
3094 Wireless link quality maximum value. Linux only.
3095 wireless_link_qual_perc (net)
3098 Wireless link quality in percents. Linux only.
3099 wireless_mode (net)
3102 Wireless mode (Managed/Ad-Hoc/Master). Linux only.
3103 words textfile
3106 Displays the number of words in the given file.
3107 xmms2_album
3110 Album in current XMMS2 song.
3111 xmms2_artist
3114 Artist in current XMMS2 song.
3115 xmms2_bar (height),(width)
3118 Bar of XMMS2's progress.
3119 xmms2_bitrate
3122 Bitrate of current song.
3123 xmms2_comment
3126 Comment in current XMMS2 song.
3127 xmms2_date
3130 Returns song's date.
3131 xmms2_duration
3134 Duration of current song.
3135 xmms2_elapsed
3138 Song's elapsed time.
3139 xmms2_genre
3142 Genre in current XMMS2 song.
3143 xmms2_id
3146 XMMS2 id of current song.
3147 xmms2_percent
3150 Percent of song's progress.
3151 xmms2_playlist
3154 Returns the XMMS2 playlist.
3155 xmms2_size
3158 Size of current song.
3159 xmms2_smart
3162 Prints the song name in either the form "artist - title" or file
3163 name, depending on whats available.
3164 xmms2_status
3167 XMMS2 status (Playing, Paused, Stopped, or Disconnected).
3168 xmms2_timesplayed
3171 Number of times a song was played (presumably).
3172 xmms2_title
3175 Title in current XMMS2 song.
3176 xmms2_tracknr
3179 Track number in current XMMS2 song.
3180 xmms2_url
3183 Full path to current song.
3184
3187 Conky features a Lua Programming API, and also ships with Lua bindings
3188 for some useful libraries. Note that the bindings require tolua++,
3189 which currently only compiles against Lua 5.1.
3190 To use Lua Conky, you first need to make sure you have a version of
3192 Conky with Lua support enabled (``conky -v'' will report this). Conky
3193 defines certain global functions and variables which can be accessed
3194 from Lua code running in Conky. Scripts must first be loaded using the
3195 lua_load configuration option. You then call functions in Lua via
3196 Conky's $lua, $lua_read, and Lua hooks.
3197 Be careful when creating threaded objects through the Lua API. You
3199 could wind up with a whole bunch of threads running if a thread is cre‐
3200 ated with each iteration.
3201 At this time, the Lua API should not be considered stable and may
3203 change drastically from one release to another as it matures.
3204 NOTE: In order to accommodate certain features in the cairo library's
3206 API, Conky will export a few additional functions for the creation of
3207 certain structures. These are documented below.
3208 conky_parse(string) function
3210 This function takes a string that is evaluated as per Conky's
3211 TEXT section, and then returns a string with the result.
3212 conky_set_update_interval(number) function
3214 Sets Conky's update interval (in seconds) to 'number'.
3215 conky_window table
3217 This table contains some information about Conky's window. The
3218 following table describes the values contained:
3219 drawable Window's drawable (Xlib Drawable), requires Lua extras
3221 enabled at compile time.
3222 visual Window's visual (Xlib Visual), requires Lua extras en‐
3223 abled at compile time.
3224 display Window's display (Xlib Display), requires Lua extras en‐
3225 abled at compile time.
3226 width Window width (in pixels).
3227 height Window height (in pixels).
3228 border_inner_margin Window's inner border margin (in pixels).
3229 border_outer_margin Window's outer border margin (in pixels).
3230 border_width Window's border width (in pixels).
3231 text_start_x The x component of the starting coordinate of text
3232 drawing.
3233 text_start_y The y component of the starting coordinate of text
3234 drawing.
3235 text_width The width of the text drawing region.
3236 text_height The height of the text drawing region.
3237 NOTE: This table is only defined when X support is enabled.
3239 conky_info table
3241 This table contains some information about Conky's internal da‐
3242 ta. The following table describes the values contained:
3243 update_interval Conky's update interval (in seconds).
3245 conky_build_info string
3247 A string containing the build info for this particular instance
3248 of Conky, including the version, build date, and architecture.
3249 conky_build_date string
3251 A string containing the build date for this particular instance
3252 of Conky.
3253 conky_build_arch string
3255 A string containing the build architecture for this particular
3256 instance of Conky.
3257 conky_version string
3259 A string containing the version of the current instance of
3260 Conky.
3261 conky_config string
3263 A string containing the path of the current Conky configuration
3264 file.
3265 cairo_text_extents_t:create() function
3267 Call this function to return a new cairo_text_extents_t struc‐
3268 ture. A creation function for this structure is not provided by
3269 the cairo API. After calling this, you should use tolua.takeown‐
3270 ership() on the return value to ensure ownership is passed prop‐
3271 erly.
3272 cairo_font_extents_t:create() function
3274 Call this function to return a new cairo_font_extents_t struc‐
3275 ture. A creation function for this structure is not provided by
3276 the cairo API. After calling this, you should use tolua.takeown‐
3277 ership() on the return value to ensure ownership is passed prop‐
3278 erly.
3279 cairo_matrix_t:create() function
3281 Call this function to return a new cairo_matrix_t structure. A
3282 creation function for this structure is not provided by the
3283 cairo API. After calling this, you should use tolua.takeowner‐
3284 ship() on the return value to ensure ownership is passed proper‐
3285 ly.
3286 cairo_text_extents_t:destroy(structure) function
3288 Call this function to free memory allocated by cairo_text_ex‐
3289 tents_t:create.
3290 cairo_font_extents_t:destroy(structure) function
3292 Call this function to free memory allocated by cairo_font_ex‐
3293 tents_t:create.
3294 cairo_matrix_t:destroy(structure) function
3296 Call this function to free memory allocated by cairo_ma‐
3297 trix_t:create.
3298
3300 conky -t '${time %D %H:%M}' -o -u 30
3301 Start Conky in its own window with date and clock as text and 30
3302 sec update interval.
3303 conky -a top_left -x 5 -y 500 -d
3305 Start Conky to background at coordinates (5, 500).
3306 conky -C > ~/.config/conky/conky.conf
3308 Do not start Conky, but have it output the builtin default con‐
3309 fig file to ~/.config/conky/conky.conf for later customising.
3310
3312 ${sysconfdir}/conky/conky.conf
3313 Default system-wide configuration file. The value of
3314 ${sysconfdir} depends on the compile-time options (most likely
3315 /etc).
3316 ~/.config/conky/conky.conf
3318 Default personal configuration file.
3319
3321 Drawing to root or some other desktop window directly doesn't work with
3322 all window managers. Especially doesn't work well with Gnome and it has
3323 been reported that it doesn't work with KDE either. Nautilus can be
3324 disabled from drawing to desktop with program gconf-editor. Uncheck
3325 show_desktop in /apps/nautilus/preferences/. There is -w switch in
3326 Conky to set some specific window id. You might find xwininfo -tree
3327 useful to find the window to draw to. You can also use -o argument
3328 which makes Conky to create its own window. If you do try running Conky
3329 in its own window, be sure to read up on the own_window_type settings
3330 and experiment.
3331
3333 https://github.com/brndnmtthws/conky
3334 #conky on irc.freenode.net
3336
3338 Copyright (c) 2005-2021 Brenden Matthews, Philip Kovacs, et. al. Any
3339 original torsmo code is licensed under the BSD license (see LICENSE.BSD
3340 for a copy). All code written since the fork of torsmo is licensed un‐
3341 der the GPL (see LICENSE.GPL for a copy), except where noted different‐
3342 ly (such as in portmon and audacious code which are LGPL, and prss
3343 which is an MIT-style license).
3344
3346 The Conky dev team (see AUTHORS for a full list of contributors).
3347 2012-05-03 conky(1)