From ArchWiki

This article or section needs language, wiki syntax or style improvements. See Help:Style for reference.

Reason: Poor style, duplicate content (Discuss in Talk:Ratpoison)

Ratpoison is a tiling window manager written in C that allows the user to manage applications without a mouse. The user interface is inspired by GNU Screen.

By default, ratpoison controls in much the same way as Emacs. Commands begin by pressing Ctrl+t, and are then followed by another combination such as Ctrl+Space to move to the next window.


Install the ratpoisonAUR package.

Using ratpoison

After X11 starts up you will see a black screen and a little textbox on the upper right of it that says "Welcome to Ratpoison". Now type Ctrl+t and then ? to get a list of keybindings. If you are used to GNU screen, you will feel at home very soon.

You are able to define custom keystrokes and even override existing ones in ~/.ratpoisonrc


# Overriding CTRL+t 'c' to start aterm instead of xterm
bind c exec aterm

bind f exec firefox

So, if you type Ctrl+t and then f, ratpoison will fire up Firefox.

Ctrl+t is the default escape key, the key used to trigger ratpoison commands. To change the mapping of the escape key to the Windows key, use the following line in your ~/.ratpoisonrc:

# Setting the escape key to the Windows key
escape Super_L

Here is a another ~/.ratpoisonrc:

exec xsetroot -cursor_name left_ptr
startup_message off
escape C-z

# Make a screenshot
alias sshot exec import -window root ~/screenshot-$(date +%F).jpg
definekey top M-C-Print sshot

#virtual desks
gnewbg one
gnewbg two

definekey top M-l exec ratpoison -c "select -" -c "gprev" -c "next"
definekey top M-h exec ratpoison -c "select -" -c "gnext" -c "next"

#switch between windows
definekey top M-j next
definekey top M-k prev

unbind c
bind c exec urxvt -tr
#bind c exec aterm

bind g exec gftp
bind f exec firefox

Tips and tricks

Screen reader accessibility

By default, ratpoison is not accessible with Orca. There is a project at https://gitlab.com/stormdragon2976/strychnine that replaces the default ratpoison widgets with GTK counterparts.

$ git clone https://gitlab.com/stormdragon2976/strychnine.git
$ cd strychnine
$ ./setup.sh

Follow the on screen prompts, and you will get a ~/.ratpoisonrc that will automatically launch Orca when it starts. See the included README.md for more options.

Java applications

Java GUI applications assume stacking window managers, and do not go to fullscreen properly with the default ratpoison configuration. See Java#Impersonate another window manager and Java#Gray window, applications not resizing with WM, menus immediately closing for solutions.

Multiple workspaces

By default, ratpoison only has one workspace, but using a script called rpws (installed by default) you can have more.

Edit your ~/.ratpoisonrc, and add:

exec /usr/bin/rpws init 6 -k

That creates 6 workspaces. By default, you can access to them by using Alt+F1 to access the first, Alt+F2 to access the second, etc.

You can also add binds to them, like this:

bind C-1 exec rpws 1
bind C-2 exec rpws 2

That allows to access them with Ctrl+t Ctrl+1 (assuming Ctrl+t as your escape key)

URxvt and xterm

URxvt and xterm, as they are installed by default, send resize hints to the window manager. This works in most tiling window managers, but not in ratpoison. The end result is that URxvt/xterm resizes itself in multiples of the font size, rather than resizing to the whole screen, and chances that there are unfilled gaps are high. There are two solutions to this problem, documented below.

Install a patched URxvt

If you use URxvt, the rxvt-unicode-fontspacing-noinc-vteclear-secondarywheelAUR package, among other improvements, sends no resize hints to the window manager. If you install this version of URxvt rather than the default, URxvt will resize properly within ratpoison.

Adjust the border

We can use the xterm/urxvt option internalBorder and set the border of ratpoison to 0.

A trial and error process must be done to find the exact number of internalBorder for each combination of resolution and font size. (the border of ratpoison must be set to 0 before doing the tests) The term command line option -b can be used to test for the correct number and then can be saved on the following files.

urxvt*internalBorder: 8 #change urxvt to xterm if necessary. Using the font terminus in urxvt at 14px size, 8 is the correct number here.
set border 0

If a combination cannot be found, you could try changing the font size and the font family also. (that changes the required border number)

Launch on startup

Examples for launching programs when ratpoison starts. File ~/.ratpoisonrc is executed by ratpoison on startup.

Launch urxvt with a tmux session
exec urxvt -e bash -c "tmux -q has-session && exec tmux attach-session -d || exec tmux new-session -n$USER -s$USER@$HOSTNAME"
Launch optimized chromium
exec bash -c 'pidof chromium &>/dev/null || exec /usr/bin/chromium --disk-cache-dir=~/tmp/cache'

Wallpaper and transparency

Example for setting transparency using xcompmgr and nitrogen. First start nitrogen and set the desired wallpaper. Then use this in your ~/.ratpoisonrc

Wallpaper and transparency
exec xcompmgr -c -f -D 5 &
exec nitrogen --restore

Useful key bindings

Key bindings Effect
Ctrl+t ! <Program Name> Start any program
Ctrl+t ? Show key bindings
Ctrl+t c Start an X terminal
Ctrl+t n Switch to next window
Ctrl+t p Switch to previous window
Ctrl+t 19 Switch to windows 1–9
Ctrl+t k Close the current window
Ctrl+t Shift+k XKill the current application
Ctrl+t s,Shift+s Split the current frame into two vertical,horizontal ones
Ctrl+t Tab, Left, Up, Right, Down Switch to the next, left, top, right, bottom frame.
Ctrl+t Shift+q Make the current frame the only one
Ctrl+t : Execute a ratpoison command

Focus follows mouse (sloppy.c)

sloppy.c is a companion program for ratpoison and can be found in /usr/share/ratpoison/. To enable focus follows mouse, run the following:

# cd /usr/share/ratpoison/
# gcc -o sloppy sloppy.c -lX11
# ./sloppy

To autostart focus follows mouse, add the following to your ~/.ratpoisonrc:

exec /usr/share/ratpoison/sloppy


Sloppy.c inhibits continued use of the keyboard to make focus changes. An improved version of focus follows mouse which does not interfere with keyboard-driven focus changes is available ratpoison-sloppymoveAUR

To autostart ratpoison-sloppymove, add the following to your ~/.ratpoisonrc:

exec ratpoison-sloppymove

Ratpoison and display managers

Many display managers (e.g., LightDM) source the available sessions from /usr/share/xsessions/ and most window managers and desktop environments create .desktop files there. However ratpoison instead creates a ratpoison.desktop file in /etc/X11/sessions/. To allow display managers to find ratpoison one may need to copy the ratpoison.desktop file from /etc/X11/sessions/ratpoison.desktop to /usr/share/xsessions/ratpoison.desktop. If the /usr/share/xsessions directory does not exist, create it as root.

See also