Documentation quick access

If you can't find what you want to know, then ask at the mailing list (recommended) or write in Your voice page.


Welcome to the Sawfish User Guide[]

Welcome to the Sawfish User Guide, the starting point for all questions regarding the use and configuration of your Sawfish window manager.

You can just skim through this document and come back later for specific questions or read it straight from top to bottom; do as you prefer. In either instance you should read this introduction so that you know what this User Guide will and won't cover and what the different conventions it uses are. After that you are free to continue on your own :-)

What the User Guide aims to be[]

The Sawfish User Guide aims to give you a first start on how to use and configure your Sawfish window manager for your every day work. It assumes no prior knowledge of its topic and aids you with step-by-step instructions as well as examples for the most common tasks.

It's supposed to be the first point of reference for any simple Sawfish configuration question and to provide you with links to sources of further information in case you have problems.

Finally you should find some tips and tricks showing you the most useful and impressive features of Sawfish shedding light on ways to save your time and effort.

What the User Guide is not[]

This User Guide assumes you have a working installation of Sawfish on your computer, either compiled from the sources or via a binary package of your distributor. It will not cover the topic of how to install Sawfish. If you have trouble installing Sawfish please read the Download and Install documentation.

It will also not cover how to interact with the Sawfish Lisp environment. Its build-in Lisp interpreter is what makes Sawfish the powerful window manager that it is, so if you want to master Sawfish and make the best use of it you will have to get familiar with its Lisp capabilities. A complete discussion of this complex topic is beyond the scope of this document. We advise you to take a look at the Sawfish Programming Manual for this.

Conventions used[]

Type of text Style Example
Text appearing in the GUI bold OK, Cancel
Filenames italic ~/.sawfish/custom
Key-strokes fixed width C-x, M-Esc, C-H-1

A quick overview of Sawfish[]


Sawfish is a lisp-extensible window manager for X11. Its aim is to allow all areas of window management (decoration, manipulation) to be customized as far as is possible, yet still remain as fast or faster than existing window managers.

Despite this extensibility its policy is very minimal compared to most window managers. It does not implement desktop backgrounds, applications docks, or other things that may be achieved through separate applications.

All high-level window management functions are implemented in Lisp for future extensibility or redefinition. Also, most received events are exported to the Lisp environment through key-bindings and hooks, similar to Emacs. These events include pointer behavior and many internal X11 events.


Using Sawfish[]

Viewports and Workspaces[]

The concept of virtual desktop may refer to two different mechanisms.

  • Workspaces: there can be multiple distinct desktops, all independent from each other. Only a single desktop can be viewed at a time. The windows can reside on each one of them (sticky windows), and windows can be sent from one desktop to the other.
  • Viewports: the size of a single desktop can be higher than the screen size. In that case only a portion of the desktop is seen at a time, and that is called a viewport. If the desktop is four times the width of the screen, there are four possible viewports. The windows can appear on every viewport, and even across the border between adjacent viewports.

Customizing Sawfish[]


To install a theme, put the archive, like "BlueBox.tar.gz", under ~/.sawfish/themes/. Then use the configurator to choose one.

You can customize the theme installation location with 'theme-load-path', for example as:

(setq theme-load-path 
     (append (list 
              "~/share/sawfish/themes" "~/foo/bar/") 

By default, theme-load-path's value is: "~/.sawfish/themes" "/usr/share/sawfish/themes" "/usr/share/sawfish/1.x.y/themes". Search is done in this order. Supported archives are tar, with gz, bz2, and Z compression. It is also possible to unpack the archive, and put each theme under their own directory. For example, theme "BlueBox" should be put under ~/.sawfish/themes/BlueBox/.

Instruction for beginners[]

To install the compressed archive, in a terminal as root, run the command

cp BlueBox.tar.gz /usr/share/sawfish/themes

If you want to install a decompressed archive instead, go to the directory where you saved the tar archive, and run the command

tar xvf BlueBox.tar.gz

You will have a directory called "BlueBox". As root, run the command

mv BlueBox /usr/share/sawfish/themes

Key and mouse bindings[]

What are bindings?[]

Whenever you interact with Sawfish in one way or another it usually involves some kind of binding: Whether it's dragging a window across the screen with your mouse, switching workspaces or closing a window via a combination of keys. All of this follows the same general scheme: You, the user, perform some kind of action – clicking, moving the mouse, pressing a key – to which Sawfish responds in a particular (and hopefully desired) fashion. This association between user performed inputs and Sawfish behavior is called binding.

Most window managers today provide a way to customize bindings. While it's usually possible to bind keys to launch applications and perform simple and common operations like minimizing a window, mouse events are often predefined and can't be changed at all. Sawfish on the other hand allows for full customization of bindings. Even if you don't notice it, every reaction to your inputs is specified by a binding and can be altered.

But bindings in Sawfish are specified by more than just a user input. You obviously don't want one action to have the same effect in every situation. Clicking on a window title should have a different effect than clicking on the root window. That's why you can define contexts for your bindings. Depending on the context, your actions have different outcomes. Clicking on the title of a window might raise it, while clicking on the window itself could raise and focus it. And clicking on the root window would pop up the application menu.

Customizing bindings[]

To customize your mouse and key bindings, launch the Sawfish Configurator and switch to the "Bindings" tab.

Bindings configurator.

Here you have a list of all the bindings defined for the context selected in the "Context" box. There are eleven different contexts you an specify bindings for. Their meanings are as follow:

  • Global: Bindings that have no particular context and are active anywhere.
  • Window: Bindings that are active on the currently focused window.
  • Root window: Bindings that are active when the pointer is in the root window (aka "Desktop").
  • Title: Bindings that are active in window titles.
  • Border: Bindings that are active in borders of window frames.
  • Close button: Bindings that are valid for the close button.
  • Iconify button: Bindings that are used for the iconify button.
  • Maximize button: Bindings that are used for the maximize button.
  • Menu button: Bindings that are used for the menu button.
  • Shade button: Bindings that are used for the shade button.
  • Sticky button: Bindings that are used for the sticky button.
  • Lock button: Bindings that are used for the lock button.
  • Rename button: Bindings that are used for the rename button.
  • Move resize button: Bindings that are used for the move-resize button.
  • Raise lower button: Bindings that are used for the raise-lower button.
  • Prompt: Bindings that are used for prompts.
  • Cycle: Bindings that are active when cycling through windows.

Of those contexts, only Global, Window, Root window, Prompt and Cycle work with key-only bindings. When a window is focused, there is no other way to determine a user input is supposed to invoke, for example, the Close button binding than clicking on the close button. The same is true for Title, Border and all button bindings.

Also note that Global bindings are overwritten by more specific bindings, eg:

(bind-keys window-keymap "A-F4" 'destroy-window-safely)

will override

(bind-keys global-keymap "A-F4" '(system "true &"))

Dialog for editing bindings.

Sample Keybinding Configuration[]

  • W = WM-Modifier (check "Modifier key(s) used for default shortcuts" in SawfishConfig)
  • C = Control,
  • H = Hyper,
  • M = Meta,
  • Super,
  • S = Shift,
    • be sure to check out the file KEYBINDINGS in the sourcetree!
( bind-keys global-keymap
  "F1"      '( system "true &" )
  "W-F3"    '( system "sawfish-config &" )
  "C-W-e"   'display-errors
  "C-W-n"   'restart
  "C-W-q"   'quit
  "C-W-a"   'view-clipboard
  "W-TAB"   'cycle-windows
  "C-TAB"   'cycle-windows-backwards
  "C-W-t"   '( system "eject -T /dev/scd0 &" )
  "W-Menu"  'popup-window-menu
  "C-Menu"  'popup-root-menu
  "S-Menu"  'popup-apps-menu
  "C-W-x"   '( system "xkill &" )
  "C-W-d"   'show-desktop
  "C-S-d"   'hide-desktop
  "C-S-i"   'iconify-all-windows
  "C-S-q"   'close-all-windows
  "Print"   '( system "import -border window.png &" )
  "C-Print" '( system "import -window root root.png &" )
  "W-F2"    `( jump-or-exec "Gnome-run-dialog" "gnome-run-dialog" t )
  "W-F6"    `( jump-or-exec "Geeqie" "geeqie" nil )
  "W-F7"    `( jump-or-exec "Iceweasel" "iceweasel" t )
  "W-F8"    `( jump-or-exec "Exaile" "exaile" t )
  "W-F9"    `( jump-or-exec "Synaptic" "gksu -u root synaptic" nil )
  "W-F10"   `( jump-or-exec "Geany" "geany" t )
  "W-F11"   `( jump-or-exec "Glade-3" "glade-3" t )
  "Home"    `( jump-or-exec "Nautilus" "nautilus --no-desktop ~" t ) )

Matching windows[]

Sample Configuration[]

An example sawfishrc:

;; Window Matchers

( add-window-matcher '( ( WM_CLASS . "^Pager/pager$" ) )
       '( ( position . south-east )
          ( fixed-positon . t )
          ( never-maximize . t )
          ( never-iconify . t )
          ( frame-type . none )
          ( cycle-skip . t )
          ( window-list-skip . t )
          ( sticky . t )
          ( sticky-viewport . t )
          ( depth .  -12 ) ) )

;; Application Keymacros

( define apps-keymap ( make-keymap ) )
( bind-keys global-keymap "W-e" apps-keymap )

( bind-keys apps-keymap
  "c" `( jump-or-exec "Claws-Mail" "claws-mail" t )
  "g" `( jump-or-exec "GPRename" "gprename" nil )
  "m" `( jump-or-exec "MPlayer" "mplayer" nil )
  "o" `( jump-or-exec "Gtkorphan" "gksu -u root gtkorphan" t )
  "s" `( jump-or-exec "" "screenlets-manager" t )
  "t" `( jump-or-exec "Flush" "flush" nil )
  "z" '( system "gksu -u root /etc/init.d/network-manager restart &" )
  "u" '( system "gksu -u root /etc/init.d/privoxy restart &" ) )

;; Animation [Yep, Sawfish Maintainers also are Human Beeings]

( define-special-variable default-window-animator 'wireframe )
( define-special-variable anim-outline-icon-coords '( 0 . 0 ) )
( define-special-variable anim-outline-steps 45 )
( define-special-variable anim-outline-delay 15 )
( define-special-variable move-outline-mode 'cross )
( define-special-variable resize-outline-mode 'elliptical )

;; Look'n'Feel

;( define-special-variable default-frame-style 'Zami-like-saw )
( define-special-variable decorate-transients t )
( define-special-variable use-custom-font-color nil )
( define-special-variable frame-font-active-color "white" )
( define-special-variable frame-font-inactive-color "grey85" )

;; Cycling

( define-special-variable cycle-all-workspaces t )
( define-special-variable cycle-all-viewports t )
( define-special-variable cycle-raise-windows nil )

Sawfish and the desktop[]

Sawfish and GNOME[]

Once upon a time Sawfish was the default GNOME WM. It was replaced by MetaCity (which will be replaced by Mutter).

With Sawfish 1.6.0 the majority of the GNOME-Integration was removed in favour of desktop-independent functions. Integration is provided for the root-menu and default-applications as well as SawfishConfig being callable from the GNOME ControlCenter.

GNOME <= 2.22[]

The easiest way to make Gnome use Sawfish as its window manager is to add Sawfish to the list of autostarted Applications:

System -> Preferences -> Sessions (or run: gnome-session-properties)

select the "Current Session" tab, *to remove* the current window manager from the list, start sawfish and set its "style" property to "Restart".

GNOME >= 2.24[]


Open the gconf-editor > navigate to /desktop/gnome/session/required_components/windowmanager and set the value to: sawfish


If that doesn't work open the gconf-editor > search for keys (not schemas) called "windowmanger" or "window_manager" and replace metacity with sawfish, afterwards start the session-properties and add gnome-wm to the list of applications to start.

Sawfish then should be launched during the next Gnome restart.

C) Adding a GNOME/Sawfish desktop manager menu entry (probably Ubuntu >= 11.10)

(Tested with lightdm, should work for GDM too problably)

Note: All the following has been put in a bash script: Sawfish_gnome_dm_setup


With root, create the file /usr/share/gnome-session/sessions/sawfish.session with:

[GNOME Session]

Create the file /usr/share/applications/sawfish.desktop with:

[Desktop Entry]
Exec=bash -c 'sawfish&'

The Exec line is a bit strange but this may avoid sawfish to wait 30s before starting up.

Create the file /usr/share/xsessions/gnome-sawfish.desktop with:

[Desktop Entry]
Name=GNOME with Sawfish
Comment=Gnome with the Sawfish window manager

Because of a bug somewhere, you need to create the file /usr/bin/gnome-session-sawfish with:

#! /bin/sh
exec gnome-session --session sawfish "$@"

and make it runnable:

# chmod +x /usr/bin/gnome-session-sawfish

Finally, gnome-panel may also wait 30s before starting up (probably because of some problem somewhere), so you can force it to start faster by adding the following line around the top of your .sawfish/rc file:

(system "(sleep 3 && gnome-panel)&")


An effective and simple solution is also to add "sawfish --replace" to the list of startup applications (i.e., GNOME starts with a different window manager, like Metacity or Compiz, which then gets replaced by Sawfish).

Sawfish and KDE[]

Sawfish does of course work with KDE, too. Any Sawfish version will work with KDE3. For KDE4 you should use Sawfish 1.6.0, as several focus-handling issues with KDE4 applications have been fixed. Also KDE4 integration for the root-menu, default-applications and SawfishConfig have been added.

KDE 3.x[]

To use sawfish inside KDE you have to set $KDEWM environmental variable just before the startkde command, like this:

export KDEWM=/usr/bin/sawfish

For example following code could be put inside your ~/.kde/env/ file

export KDEWM=/usr/bin/sawfish

KDE 4.x[]

Sawfish < 1.6.0[]

create the following sawfish.desktop file:

[Desktop Entry]

run the following command to get a directory to save the file in:

kde4-config --install data

choose one of the listed directories and append /ksmserver/windowmanagers/ to it, example:


Sawfish >= 1.6.0[]

a working sawfish.desktop file is provided from this version on. To choose Sawfish, simply go to:

systemsettings > personal > default applications > window manager

and choose sawfish from the combobox provided.

Then KDE will work together along with sawfish.

Other Desktop Environments[]

For XFCE4 the following ~/.xsession or ~/.xinitrc file can be used:

xscreensaver -no-splash &
sawfish &
xfce4-panel &
exec xfdesktop

See also[]