From Gentoo Wiki
Jump to:navigation Jump to:search

WeeChat is a light, extensible, actively maintained, well documented, highly featured text-mode IRC client. WeeChat natively runs through ncurses for the text-mode interface, however for user convenience many 'remote' interfaces (GUIs) are available to relay WeeChat data to more accessible mediums (Android phones, Web interfaces, X GUIs, and more).


USE flags

USE flags for net-irc/weechat Portable and multi-interface IRC client

alias Enable plugin for alias control
buflist Enable buflist plugin
charset Enable encoding conversions
doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
enchant Enable spell checker plugin via Enchant instead of GNU Aspell
exec Enable exec plugin
fifo Enable FIFO support (sh pipes)
fset Enable fast set plugin
guile Add support for the guile Scheme interpreter
irc Enable IRC protocol support
logger Enable support for logging
lua Enable Lua scripting support
man Build and install man pages
nls Add Native Language Support (using gettext - GNU locale utilities)
perl Add optional support/bindings for the Perl language
python Add optional support/bindings for the Python language
relay Enable relay plugin (experimental)
relay-api Enable json API support for the relay plugin (experimental)
ruby Add support/bindings for the Ruby language
scripts Build infrastructure for scripting
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
spell Add dictionary support
tcl Add support the Tcl language
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
trigger Enable trigger plugin
typing Enable typing plugin
verify-sig Verify upstream signatures on distfiles
xfer Enable xfer plugin support
zstd Enable support for ZSTD compression


Install WeeChat:

root #emerge --ask net-irc/weechat


An excellent quick start guide can be found on WeeChat's website. The official guide should be followed for the most up to date configuration instructions. Head over there and read the guide. When finished return here if necessary for further instructions.

Add IRC server

To be able to chat on IRC, the client must be connected to an IRC server. For this section, the libera server network will be used as an example.

At the IRC input box, add the libera server:

/server add libera irc.libera.chat/6697 -ssl -username=larry -ssl -ssl_verify

Connect to the server:

/connect libera

For WeeChat 4.0 and later, use -tls[1] instead of -ssl:

/server add libera irc.libera.chat/6697 -tls -username=larry

The option -tls_verify is on by default.[2]

SASL authentication

By default, some passwords are hidden behind asterisks. More options can be added under 'irc.look.nicks hide password' for different services to mask the password (ex. nickbot).

If SASL is available on the server, it is possible to use it for authentication (the user will be identified before joining channels).

Set the username for the server, substituting larry in the example below with the appropriate username:

/set irc.server.libera.sasl_username "larry"

Set the password for the server, substituting xxxxxxxx in the example below with the appropriate password:

/set irc.server.libera.sasl_password "xxxxxxxx"

Running a command when connecting to a server

It is possible to run a command automatically upon connecting to server. Use the /set irc.server.libera.command command to set up commands to run on connection.

For example, to authenticate with nickserv on connection (necessary only when not using SASL for authentication). Substitute xxxxxxxx in the example below with the appropriate password:

/set irc.server.libera.command "/msg nickserv identify xxxxxxxx"
Multiple commands command can be separated with a ; (semi-colon).

Securing passwords

It is possible to protect passwords in configuration files to keep secure from prying eyes.

The first step to protect passwords is to setup a passphrase with the /secure passphrase command:

/secure passphrase <this is my secret passphrase>

Then add a secured data with the libera password:

/secure set libera_password xxxxxxx

Then use ${sec.data.libera_password} instead of the password in the IRC options mentioned above, for example:

/set irc.server.libera.sasl_password "${sec.data.libera_password}"

Auto-join channels

To auto-join specific channels when connecting to server, configure WeeChat to automatically update the autojoin option when joining or leaving channels with the following command:

/set irc.server_default.autojoin_dynamic on

Todo: Todo:

  • Make section independent of external guide

After making it through step 7 in the WeeChat quick start guide Libera.Chat should be added as the server.

Custom channels can be automatically joined each time WeeChat is opened by running the following command inside the WeeChat client. For example, to add #gentoo (webchat) and #gentoo-chat (webchat) channels to the auto-join list each time weechat starts:

/set irc.server.libera.autojoin "#gentoo,#gentoo-chat"

Add or subtract more more channels to the comma separated list as desired. Everyone has their own channels interests!

Fast set

The "fast set" plugin displays a list of options in a buffer, and helps to set WeeChat and plugin options.

Example usage

Show IRC options changed:

/fset d:irc.*

Show all options with "nicklist" in name:

/fset nicklist

Show how all values which contain "red":

/fset =red

Show all values which are exactly "red":

/fset ==red

Smart filter

A new smart filter for IRC join/part/quit message has been added. It is disabled by default (to see all join/part/quit by default).

When a nick spoke on channel during past X minutes (where X is delay irc.look.smart_filter_delay), its join/part/quit will be displayed by default. Otherwise, if nick did not speak for a long time, all join/part/quit messages will be tagged with "irc_smart_filter". Define a filter on this tag to hide join/part/quit from users that are not speaking on channel, in the example below delay is set to 5 min:

/set irc.look.smart_filter on
/filter add irc_smart * irc_smart_filter *
/set irc.look.smart_filter_delay 5


Todo: Todo:

  • Provide more context of what is being done here, and maybe a lead-in on what scripts are.

Enable download of files from the scripts repository when the /script command is used (list of scripts and scripts themselves); the list of scripts is downloaded from the URL specified in the option script.scripts.url; WeeChat will sometimes download again the list of scripts when using the /script command, even if no script is installed:

/set script.scripts.download_enabled on

List collections of WeeChat scripts written by external contributors, which can be installed directly in WeeChat



Plugins for WeeChat can be added and removed via USE flags. See the USE flags section above for a list of available plugins.


Occasionally spammers/trolls will attempt to scrape IRC networks for any relevant information they can find exposed about the IRC connection. Those concerned about hardening can restrict WeeChat to not provide specific details concerning their use.

These options can be set by hand in the ~.weechat/irc.conf file.


To block CTCP requests set an empty string:

/set irc.ctcp.version ""

Part and quit messages

The part and quit messages can contain custom text:

/set irc.server_default.msg_part "Ciao!"
/set irc.server_default.msg_quit "Connection severed."

Alternatively, these messages can be nullified in order to not share any information when leaving a channel or disconnecting from a network:

/set irc.server_default.msg_part "Ciao!"
/set irc.server_default.msg_quit "Connection severed."


Adding a relay

In order to use remote interfaces, WeeChat needs to be configured as a relay. Substitute <port_number> with a specific port above 1024, port 9001 is suggested for this purpose:

/relay add weechat <port_number>

Next set the password for the relay:

/set relay.network.password <password>

Adding an encrypted relay

An encrypted relay will ensure communications go directly between a browser and WeeChat relay, resulting in a greater level of privacy. All settings will be saved locally in the browser between sessions. Let's Encrypt can be used to make the process of certificate creation and renewal easier.

root #mkdir -p ~/.config/weechat/tls
root #openssl req -nodes -newkey rsa:2048 -keyout relay.pem -x509 -days 3650 -out ~/.config/weechat/tls/relay.pem

Configure Let's Encrypt and obtain the certificate:

root #certbot certonly --standalone -d <domain>
root #install -d -m 0755 -o username -g username ~/.config/weechat/tls/
root #mkdir -p ~/.weechat/tls
root #cat /etc/letsencrypt/live/<domain>/{fullchain,privkey}.pem > ~/.config/weechat/tls/relay.pem
root #chown -R username:username ~/.config/weechat/tls/

Then in WeeChat:

/relay add ssl.irc.freenode 8001
/relay add ssl.weechat 9001
/relay sslcertkey

WeeChat will now serve clients on these ports using SSL. One can connect to the computer with the WeeChat relay by setting up a self-hosted relay or visiting https://glowing-bear.org and chatting directly from a web browser.

Time-based One-Time Password (TOTP)

TOTP (Time-based One-Time Password) support has been added in WeeChat, which can now generate and check TOTP validity.

A TOTP is generated with:

  • The secret (encoded in base 32),
  • The time (by default 0, which is the current time),
  • The number of digits (4 to 10 digits are supported, 6 is the default and recommended value).
/secure set relay_totp_secret xxxxx
/set relay.network.totp_secret "${sec.data.relay_totp_secret}"

If the password is valid and that TOTP is valid for the current time, the authentication is successful.

It is also possible to generate or validate TOTP with two new infos within WeeChat:

  • totp_generate: generate a TOTP
  • totp_validate: validate a TOTP

For example to show the value of TOTP for the secret secretbase32, current time, with 6 digits

/eval -n ${info:totp_generate,secretbase32,0,6}

Remote interfaces

The following remote interfaces are available:

  • Glowing Bear - A web frontend for WeeChat. See the Glowing Bear Guide for hosting Glowing Bear on Gentoo.
  • QWeeChat - A Qt interface for WeeChat.
  • WeeChat Android - Only works on Android phones. Simply download the application from the Google Play Store and get started!
  • Emacs - A weird emacs thing.
  • WeeCloud - A WeeChat client written in javascript.

Each remote interface has a unique setup. Not all of the clients available in the list above may be operational. Glowing Bear is probably the most tested of the bunch.


It is common for many text-mode IRC client users to run the clients on a system that is always on always connected to the internet. This make it possible to never miss a mention or a message. Like most command-line programs, weechat will run all the time if opened in a screen or a tmux session which is then detached. This is currently the ideal method for staying connected to IRC networks continuously.


user $weechat --help
WeeChat 3.8 Copyright (C) 2003-2023, compiled on Mar 28 2023 16:05:07
Developed by Sébastien Helleu <flashcode@flashtux.org> - https://weechat.org/

Usage: weechat [option...] [plugin:option...]

  -a, --no-connect         disable auto-connect to servers at startup
  -c, --colors             display default colors in terminal
  -d, --dir <path>         force a single WeeChat home directory
                           or 4 different directories separated by colons (in this order: config, data, cache, runtime)
                           (environment variable WEECHAT_HOME is read if this option is not given)
  -t, --temp-dir           create a temporary WeeChat home directory and delete it on exit
                           (incompatible with option "-d")
  -h, --help               display this help
  -l, --license            display WeeChat license
  -p, --no-plugin          don't load any plugin at startup
  -P, --plugins <plugins>  load only these plugins at startup
                           (see /help weechat.plugin.autoload)
  -r, --run-command <cmd>  run command(s) after startup;
                           many commands can be separated by semicolons and are evaluated,
                           this option can be given multiple times
  -s, --no-script          don't load any script at startup
      --upgrade            upgrade WeeChat using session files (see /help upgrade in WeeChat)
  -v, --version            display WeeChat version
  plugin:option            option for plugin (see man weechat)

Debug options (for tools like valgrind, DO NOT USE IN PRODUCTION):
      --no-dlclose         do not call function dlclose after plugins are unloaded
      --no-gnutls          disable init/deinit of gnutls
      --no-gcrypt          disable init/deinit of gcrypt


Open screen using the following command:

user $screen -t weechat

After weechat is configured press Ctrl+a to enter Command Mode and then d to detach from the screen session. It can be re-attached to later by running:

user $screen -ls

To list the currently running sessions and then entering:

user $screen -r <session>

Where <session> is a weird, crazy string.

For additional information on how to use screen visit the screen article.


To open a new tmux session for weechat, the following command can be used:

user $tmux new-session -s weechat weechat

To start it as a daemon, use:

user $tmux new-session -d -s weechat weechat

To attach to the session (if started as a daemon), run:

user $tmux attach-session -t weechat

This can be executed on login using:

FILE ~/.bashrcStart weechat on shell login
if [[ $(ps -ef | grep -c tmux) -eq 1 ]] || ([[ $(ps -ef | grep -c tmux) -ne 1 ]] && ! tmux has-session -t weechat) ; then
    echo "Starting weechat tmux session"
    tmux new-session -d -s weechat weechat

After weechat has been configured, disconnect from the session by using Ctrl+b and then press d to detach.

In order to reconnect to the tmux session that is running (which was titled weechat) issue:

user $tmux attach-session -t weechat

For additional information on how to use tmux visit the tmux article.


After emerging updates, weechat can be 'in-place' upgraded without losing the currently open buffer list. This is performed by running the following command inside the weechat client:


See the upstream user guide for more additional details.


Mouse usage

Mouse usage is not enabled by default. To enable it (at startup):

/set weechat.look.mouse on
/mouse enable



Remove WeeChat:

root #emerge --ask --depclean --verbose net-irc/weechat

Configuration and logs

This will delete all message history and any saved settings.

After unmerging, for a full clean-up, be sure to remove old logs and individual user configuration from their default location in each weechat user's home directory:

user $rm -rf ~/.config/weechat/
user $rm -rf ~/.local/share/weechat/logs/

See also

  • IRC/Guide — provides a broad overview of concepts related to IRC.
  • Irssi — a powerful text-mode IRC client for connecting to internet relay chat (IRC) networks.
  • Quassel — a daemon/headless IRC client written in C++ that supports 24/7 connectivity.

External resources