WeeChat FAQ (Frequently Asked Questions)

"Wee" is a recursive acronym and stands for "Wee Enhanced Environment". So complete name is "Wee Enhanced Environment for Chat".

"Wee" also means "very small" (and yes, there is other meaning, but it does not apply to WeeChat!).

Because WeeChat is very light and brings innovating features.

More info on the WeeChat features page ^↗.

Some remote GUIs are available, see the remote interfaces page ^↗.

WeeChat must be compiled with CMake.

Please follow build instructions ^↗ and ensure all required dependencies are installed.

If you still have issues, please report them to the developers.

It is recommended to use Homebrew ^↗, you can get help with:

You can install WeeChat with this command:

For help you can type /help. For help about a command, type /help command. Keys ^↗ and commands ^↗ are listed in documentation.

It’s recommended for new users to read the Quickstart guide ^↗.

It’s a common issue with a variety of causes, please read carefully and check ALL solutions below:

This may be caused by a libc bug in function wcwidth, which should be fixed in glibc 2.22 (maybe not yet available in your distribution).

There is a workaround to use the fixed wcwidth function: https://blog.nytsoi.net/2015/05/04/emoji-support-for-weechat ^↗

See this bug report ^↗ for more information.

This may be caused by a bad value of the TERM variable in your shell (look at the output of echo $TERM in your terminal).

Depending on where you launch WeeChat, you should have:

If needed, fix your TERM variable: export TERM="xxx".

This may be caused by bad value of the TERM variable in your shell (look at output of echo $TERM in your terminal, outside screen/tmux).
For example, xterm-color may display such weird chars, you can use xterm which is OK (like many other values).
If needed, fix your TERM variable: export TERM="xxx".

If you are using gnome-terminal, check that the option "Ambiguous-width characters" in menu Preferences/Profile/Compatibility is set to narrow.

If you compiled ncursesw yourself, try to use standard ncurses (that comes with system).

Moreover, under macOS, it is recommended to install WeeChat with Homebrew package manager.

A buffer is composed by a number, a name, lines displayed (and some other data).

A window is a screen area which displays a buffer. It is possible to split your screen into many windows.

Each window displays one buffer, or a set of merged buffers. A buffer can be hidden (not displayed by a window) or displayed by one or more windows.

The plugin buflist ^↗ is loaded and enabled by default.

To limit size of bar:

To move bar to bottom:

To scroll the bar: if mouse is enabled (key: Alt+m), you can scroll the bar with your mouse wheel.

Default keys to scroll buflist bar are F1 (or Ctrl+F1), F2 (or Ctrl+F2), Alt+F1 and Alt+F2.

You can browse all buflist options with the command:

The background of the active buffer is blue by default, you can change it like this, for example to red:

The buflist plugin provides lot of options that you can customize, please read the help on each option.

There’s also a wiki page ^↗ with examples of advanced buflist configuration.

To reduce max length of nicks in chat area:

To remove nick alignment:

This is called the "hotlist", a list of buffers with the number of unread messages, by order: highlights, private messages, messages, other messages (like join/part).
The number of "unread message" is the number of new messages displayed/received since you visited the buffer.

In the example [H: 3(1,8), 2(4)], there are:

The color of the buffer/counter depends on the type of message, default colors are:

These colors can be changed with the options weechat.color.status_data_* (buffers) and weechat.color.status_count_* (counters).
Other hotlist options can be changed with the options weechat.look.hotlist_*.

See User’s guide / Screen layout ^↗ for more info about the hotlist.

The option size in input bar can be set to a value greater than 1 (for fixed size, default size is 1) or 0 for dynamic size, and then option size_max will set the max size (0 = no limit).

Example with dynamic size:

Max size of 2:

Yes, you will have to create a bar with type "root" (with an item to know in which window you are), then delete current input bar.

For example:

If ever you are not satisfied with that, just delete new bar, WeeChat will automatically create default bar "input" if item "input_text" is not used in any bar:

You can use the bare display (default key: Alt+l (L)), which shows just the contents of the currently selected window, without any formatting.

You can use a terminal with rectangular selection (like rxvt-unicode, konsole, gnome-terminal, etc.). Key is usually Ctrl + Alt + mouse selection.

You can toggle nicklist and make it visible only when needed, with key Alt+Shift+N.

Another solution is to move nicklist to top or bottom, for example:

You can use the bare display (default key: Alt+l (L)).

To make opening URLs easier, you can:

You can enable option "eat_newline_glitch", so that new line char is not added at the end of each line displayed (it will not break URL selection):

Other solution is to use a script:

Sure it is possible:

There is no option in WeeChat to change the timezone, the environment variable TZ must be set to the appropriate value.

In your shell initialization file or on command line, before starting WeeChat:

In WeeChat, the new value is immediately used:

First check that your TERM environment variable is correct, recommended values are:

If you are using screen, you can add this line to your ~/.screenrc:

If your TERM variable has a wrong value and that WeeChat is already running, you can change it with these two commands:

You can use any color number in options (optional: you can add color aliases with command /color).

Please read the User’s guide / Colors ^↗ for more information about colors management.

The default key is Ctrl+r (command is: /input search_text_here). And jump to highlights: Alt+p / Alt+n.

See User’s guide / Key bindings ^↗ for more info about this feature.

You must enable the focus events with a special code sent to terminal.

Important:

To send the code when WeeChat is starting:

And then you bind two keys for the focus (replace the /print commands by the commands of your choice):

For example to mark buffers as read when the terminal loses the focus:

This is caused by the bracketed paste option which is enabled by default, and not properly handled by screen in other windows.

You can just disable bracketed paste mode:

You can remove side bars (buflist and nicklist), change time format to display only hours and minutes, disable alignment of messages and set a char for nick prefix/suffix:

Terminal 80x25, with default configuration:

Terminal 80x25, after changes:

If you’re using some terminals like xterm or uxterm, some meta keys do not work by default. You can add a line in file ~/.Xresources:

And then reload resources (xrdb -override ~/.Xresources) or restart X.

If you are using the macOS Terminal app, enable the option "Use option as meta key" in menu Settings/Keyboard after which you can use the Option key as meta key.

If you run a WeeChat < 4.0.0 with configuration files created by any version ≥ 4.0.0, the keys names become invalid and many keys won’t work at all.
To repair them, exit WeeChat, remove all sections [key*] from weechat.conf and start WeeChat again: all default keys will be created.

The key F11 is commonly used by terminals to maximize the window, and F11/F12 are the default keys in WeeChat to scroll the nicklist.

You can bind other keys, for example Shift+F11 and Shift+F12, with WeeChat ≥ 4.0.0:

Other solution is to enable mouse (key: Alt+m) and scroll with the mouse wheel (see also questions about mouse).

Key bindings are customizable with /key command.

Default key Alt+k lets you grab key code and insert it in command line.

The key is Alt+j and then 2 digits, for example Alt+j, 1, 1 to jump to buffer 11.

You can bind a key, for example:

List of default keys is in User’s guide / Key bindings ^↗.

To jump to buffers with number ≥ 100, you could define a trigger and then use commands like /123 to jump to buffer #123:

For an easy jump to buffers, you can also install the go.py script:

You can bind the up and down keys on global history (default keys for global history are Ctrl+↑ and Ctrl+↓).

Example:

With WeeChat ≤ 3.8, you must use the raw key code (press Alt+k then key to display its code):

First try to enable mouse:

If mouse is still not working, check the TERM variable in your shell (look at output of echo $TERM in your terminal). According to terminfo used, mouse may not be supported.

You can test mouse support in terminal:

And then click on first char of terminal (upper left). You should see " !!#!!".

To disable mouse in terminal:

Some terminals are sending only ISO chars for mouse coordinates, so it does not work for X/Y greater than 94 (or 222).

You should use a terminal that supports UTF-8 coordinates for mouse, like rxvt-unicode.

When mouse is enabled in WeeChat, you can use Shift modifier to select or click in terminal, as if the mouse was disabled (on some terminals like iTerm, you have to use Alt instead of Shift).

If you are using macOS, you must install openssl from Homebrew. A CA file will be bootstrapped using certificates from the system keychain.

If you see errors about gnutls handshake, you can try to use a smaller Diffie-Hellman key (default is 2048):

If you see errors about certificate, you can disable "tls_verify" (be careful, connection will be less secure by doing that):

If the server has an invalid certificate and you know what the certificate should be, you can specify the fingerprint (SHA-512, SHA-256 or SHA-1):

You can try a different priority string, replace "xxx" by your server name:

Check that you have certificates installed on your system, this is commonly provided by the package "ca-certificates".

Setup server port, TLS, then connect:

Some servers like twitch require oauth to connect.

The oauth is simply a password with the value "oauth:XXXX".

You can add such server and connect with following commands (replace name and address by appropriate values):

If the server supports SASL, you should use that instead of sending the command for nickserv authentication, for example:

If the server does not support SASL, you can add a delay (between command and join of channels):

With WeeChat ≥ 3.5, you can automatically record the channels you manually join and part in the "autojoin" server option.

For all servers:

For a single server:

You can also add the current channel in the "autojoin" server option using the /autojoin command:

Or another channel:

There are also scripts:

The /ignore command is an IRC command, so it applies only for IRC buffers (servers and channels). It lets you ignore some nicks or hostnames of users for a server or channel (command will not apply on content of messages). Matching messages are deleted by IRC plugin before display (so you’ll never see them, and can’t be recovered by removing the ignore).

The /filter command is a WeeChat core command, so it applies to any buffer. It lets you filter some lines in buffers with tags or regular expression for prefix and content of line. Filtered lines are only hidden, not deleted, and you can see them if you disable filters (by default, the key Alt+= toggles filters).

See User’s guide / IRC smart filter ^↗.

You can choose which messages are displayed when joining a channel with the option irc.look.display_join_message (see /help irc.look.display_join_message for more info).

To hide messages (but keep them in buffer), you can filter them using the tag (for example irc_329 for channel creation date). See /help filter for help with filters.

It’s not easy to filter voice messages, because voice mode can be set with other modes in same IRC message.

If you want to do that, it’s probably because Bitlbee is using voice to show away users, and you are flooded with voice messages. Therefore, you can change that and let WeeChat use a special color for away nicks in nicklist.

For Bitlbee ≥ 3, issue this on control channel &bitlbee:

For older version of Bitlbee, issue this on control channel &bitlbee:

For checking away nicks in WeeChat, see question about away nicks.

If you really want to filter voice messages, you can use this command, but this is not perfect (will work only if first mode changed is voice):

You have to set option irc.server_default.away_check to a positive value (minutes between each check of away nicks).

You can set option irc.server_default.away_check_max_nicks to limit away check on small channels only.

For example, check every 5 minutes for away nicks, for channels with max 25 nicks:

There is a default trigger "beep" which sends a BEL to the terminal on a highlight or private message. Thus you can configure your terminal (or multiplexer like screen/tmux) to run a command or play a sound when a BEL occurs.

Or you can add a command in "beep" trigger:

With an older WeeChat, you can use a script like beep.pl or launcher.pl.

For launcher.pl, you have to setup a command:

Other scripts on this subject:

You can use the hotlist_max_level_nicks_add ^↗ buffer property to set the max hotlist level for some nicks, per buffer, or per group of buffers (like IRC servers).

To only disable highlights, you’d have to set it to 2.

For the current buffer:

For all channels on server "libera":

The default key is Ctrl+x (command is: /buffer switch).

Under OpenBSD, plugin filenames end with ".so.0.0" (".so" for Linux).

You must set that up:

You can use the command /script to install and manage scripts (see /help script for help).

Scripts are not compatible with other IRC clients.

First check questions about TLS connection in this FAQ.

If still not working, try to manually delete the scripts file (in your shell):

And update scripts again in WeeChat:

If you still have an error, then you must disable the automatic update of file in WeeChat and download the file manually outside WeeChat (that means you’ll have to update manually the file yourself to get updates):

If you’re running macOS and the downloaded file has a size of 0 bytes, try to set this variable in your shell initialization file or on command line, before starting WeeChat:

You have to reload the spell plugin:

You can, but this is NOT recommended.

Command /set in WeeChat is recommended:

If you still want to edit files by hand, you should be careful:

You can try following tips to consume less memory:

You can follow same tips as for memory, and these ones:

Disable IRC part and quit messages:

Disable answers to all CTCP queries:

With WeeChat < 4.1.0, other CTCP queries were replied by default and must be disabled as well:

Unload and disable auto-loading of "xfer" plugin (used for IRC DCC):

Define a passphrase and use secured data wherever you can for sensitive data like passwords: see /help secure and /help on options (if you can use secured data, it is written in the help). See also User’s guide / Secured data ^↗.

For example:

You can share configuration files *.conf except the file sec.conf which contains your passwords ciphered with your passphrase.

Some other files may contain sensitive info like passwords (if they are not stored in sec.conf with the /secure command).

See the User’s guide / Files and directories ^↗ for more information about configuration files.

First check directories used by WeeChat with this command: /debug dirs.
Directories home/config and home/data must be copied (all files and sub-directories).

For example if you’re using XDG directories (default with WeeChat ≥ 3.2), the directories should be $HOME/.config/weechat and $HOME/.local/share/weechat.
If you’re using a single directory (default with WeeChat < 3.2), the directory should be $HOME/.weechat.

Steps:

See this page ^↗.

When you run WeeChat under gdb, you may have this error:

To fix that, you can run gdb with this command (replace path to libpthread and WeeChat with paths on your system):

WeeChat runs fine on most Linux/BSD distributions, GNU/Hurd, macOS and Windows (Cygwin and Windows Subsystem for Linux).

We do our best to run on as many platforms as possible. Help is welcome for some OS' we don’t have, to test WeeChat.

There are many tasks to do (testing, code, documentation, etc.)

Please contact us via IRC or mail, look at support page ^↗.

You can give us money to help development. Details on donation page ^↗.