1. Start WeeChat
A recommended terminal emulator for X (but not mandatory) is rxvt-unicode (it has good UTF-8 support, and no problem with default keyboard bindings).
Run from your shell:
2. Online help / options
WeeChat has help for all commands, just issue:
To get help on a specific command, issue:
To set options, issue:
/set config.section.option value
config is configuration name (
weechat for core, or a plugin
section the section of this configuration and
WeeChat immediately uses the new value (you never need to restart WeeChat after changes to configuration).
You can use
/set option with partial name and wildcard "*" at the beginning
or end to display all options containing letters.
display all options (WeeChat and plugins):
display WeeChat options:
display IRC plugin options:
You can display help for an option with
/help, for example:
All settings are saved when WeeChat ends (or with
/save command to force
a write of the options).
You can edit configuration files (*.conf) by hand and reload them by
/reload command if you don’t want to use
3. Core vs plugins
WeeChat "core" is only used to display data on screen and interact with the user, that means weechat core without plugins is useless (faithful users: IRC was part of core for versions ≤ 0.2.6).
All network protocols like IRC are provided in separate plugins.
/plugin command to list loaded plugins, you should see "irc" and
other plugins in the list.
4. Create an IRC server
The server freenode is created by default on first startup.
You can add another IRC server with
/server command, for example:
/server add oftc irc.oftc.net/6667
As usual, help is available if you’re lost:
5. Set custom IRC server options
WeeChat uses default values for all servers ("fall backs"), if you don’t specify a specific value for a server option. These default options are "irc.server_default.*".
For each server option, WeeChat uses its value if it is defined (not "null"). Otherwise WeeChat uses default value ("irc.server_default.xxx").
For example there’s default nicks (based on your un*x login), and you can override them for freenode server with following command:
/set irc.server.freenode.nicks "mynick,mynick2,mynick3,mynick4,mynick5"
To set username and realname:
/set irc.server.freenode.username "My user name" /set irc.server.freenode.realname "My real name"
To enable auto-connect to server at startup:
/set irc.server.freenode.autoconnect on
If SASL is available on server, you can use it for authentication (you will be identified before you join channels):
/set irc.server_default.sasl_mechanism dh-blowfish /set irc.server.freenode.sasl_username "mynick" /set irc.server.freenode.sasl_password "xxxxxxx"
To run a command after connection to server, for example to authenticate with nickserv (only if you don’t use SASL for authentication):
/set irc.server.freenode.command "/msg nickserv identify xxxxxxx"
|Many commands can be separated by ; (semi-colon).|
To auto-join some channels when connecting to server:
/set irc.server.freenode.autojoin "#channel1,#channel2"
To remove a value of a server option, and use the default value instead, for example to use default nicks (irc.server_default.nicks):
/set irc.server.freenode.nicks null
Other options: you can setup other options with following command ("xxx" is option name):
/set irc.server.freenode.xxx value
6. Connect to IRC server and auto-join channels
|This command can be used to create and connect to a new server without using
By default, server buffers are merged with WeeChat core buffer. To switch between core buffer and server buffers, you can use ctrl+x.
It is possible to disable auto merge of server buffers to have independent server buffers:
/set irc.look.server_buffer independent
7. Join/part IRC channels
Join a channel:
Part a channel (keeping buffer open):
/part [quit message]
Close server or channel buffer (
/close is an alias for
8. Buffer/window management
A buffer is a component linked to a plugin with a number, a category, and a name. A buffer contains the data displayed on the screen.
A window is a view on a buffer. By default there’s only one window displaying one buffer. If you split screen, you will see many windows with many buffers at same time.
Commands to manage buffers and windows:
(I’ll not repeat here that you can get help with /help on these commands)
For example, to vertically split your screen into a small window (1/3 width), and a large window (2/3), use command:
/window splitv 33
9. Key bindings
WeeChat uses many keys by default. All these keys are in the documentation, but you should know at least some vital keys:
alt+←/→ or F5/F6: switch to previous/next buffer
F7/F8: switch to previous/next window (when screen is split)
F9/F10: scroll title bar
F11/F12: scroll nicklist
Tab: complete text in input bar, like in your shell
PgUp/PgDn: scroll text in current buffer
alt+a: jump to buffer with activity (in hotlist)
According to your keyboard and/or your needs, you can rebind any key
to a command with
A useful key is alt+k to find key codes.
For example, to bind alt+y to command
/key bind (press alt-k) (press alt-y) /buffer close
You’ll have a command line like:
/key bind meta-y /buffer close
To remove key:
/key unbind meta-y
On some distros like Debian, plugins are available via a separate package (like weechat-plugins). Plugins are automatically loaded when found (please look at the WeeChat documentation to load/unload plugins or scripts).
Many external scripts (from contributors) are available for WeeChat: http://weechat.org/scripts
You can manage scripts in WeeChat with command
for more info).
11. More documentation
You can now use WeeChat and read FAQ/documentation for any other questions: http://weechat.org/doc
Enjoy using WeeChat!