Gentoo Wiki


Desktop environments

Lightweight desktop environments

Window managers

Compositing window managers





This guide will tell you how to write your own configuration file for FVWM. This is not an easy step (this is almost more programming than editing), and if you'd just like something quick and easy, or don't even have FVWM installed yet, I'd suggest you read FVWM.

Starting Up

From a Console

You can get into FVWM pretty quickly by at a console:

XSESSION=fvwm2 startx -- :1 vt8

This is done so that should something go wrong, we can still startx, and get into our normal desktop to get some help, or just get back to life for a while.

To get back into FVWM after switching away, hit Ctrl + Alt + F8.

From KDM

You need to place fvwm.desktop in /usr/share/xsessions/

Setting up our Basics

This howto is a guide, with the word "Advanced" in the name. As such, you are expected to tweak as you go. Your final config will probably look quite different from mine (especially if you're a KDE person :-p).

I've seen way too many FVWM configuration files that are insanely complex, and to make one change, you have to go through a few hundred or thousand of lines of code. We're going to keep this simple and logical. Modular would be a good way to describe our configuration. The default configuration file is called ~/.fvwm/config (or ~/.fvwm/.fvwm2rc for versions prior to 2.5.10). From this file the modular configuration will be read by the command Read. For example, we can define a pager in the file ~/.fvwm/pager and read it from config.

Read pager

You'll always have to keep in mind that if you don't understand something, you can read the man pages: You can reach the main man page with:

man fvwm

At the beginning you will need frequent access to fvwm man pages. You could follow these instructions to have fvwm man pages in your menu. If you use KDE applications you could also use khelpcenter to read man pages. The Official FVWM Home Page has a handy man page with hyperlinks.

Commands, Functions and Modules

To start, FVWM reads the config file (and all files read by config). After reading the whole of the configuration it executes StartFunction (if defined) and then InitFunction (if defined).

Commands refer both to configuration commands. Look at the list of fvwm commands. The following command defines a desktop sixe of 3x2 pages.

DesktopSize 3x2

Modules. As the man page states, a module is a separate program which runs as a separate Unix process but transmits commands to FVWM to execute. FVWM comes with a pre-defined number of modules, and you will find here the commands to configure them. For example, the FVWM man page mentions FvwmBacker as the module that changes the background when you change desktops. First, you have a look at the man page of FvwmBacker to know its syntax.

# man FvwmBacker

Now, you can define FvwmBacker. This example defines six different backgrounds for the pages defined by the previous DesktopSize command.

DestroyModuleConfig FvwmBacker:*
*FvwmBacker: Command (Desk 0, Page 0 0) Exec xsetbg -fullscreen 1_HAL_9000_eye.jpg
*FvwmBacker: Command (Desk 0, Page 1 0) Exec xsetbg -fullscreen 2_Royal_Mail_by_l8.jpg
*FvwmBacker: Command (Desk 0, Page 2 0) Exec xsetbg -fullscreen 3_linux-code.jpg
*FvwmBacker: Command (Desk 0, Page 0 1) Exec xsetbg -fullscreen 4_the_f33r3x_web.jpg
*FvwmBacker: Command (Desk 0, Page 1 1) Exec xsetbg -fullscreen 5_Thalo_Blyue_Cyborg_by_King_Nathan.png
*FvwmBacker: Command (Desk 0, Page 2 1) Exec xsetbg -tile 6_LookClosely_by_sanfranguy.jpg
Module FvwmBacker

In the next example, the command Style defines the style (where and how) of FvwmButtons module with alias Confi (you can have different FvwmButtons running with different alias). The style defines that the module will appear on page 0,0, without the buttons 1,2 and 4, and it will not show in the window list of active programmes. The definition of the module Confi follows.

Style Confi StartsOnPage 0 0 0,!Button 1,!Button 2,!Button 4,!Borders,WindowListSkip
DestroyModuleConfig Confi: * # Destroy previous module configuration.
# We define the module Confi...
*Confi: Rows 3               # that has 3 rows of buttons
*Confi: Columns 2            # and two colums of buttons
*Confi: Geometry 60x90+0+0   # Size 60x90 on the top of the screen
*Confi: Back rgb:ff/ff/99    # yellow
                             # First button executes konqueror
*Confi: (1x1, Icon konqueror.png, Action(Mouse 1) 'Exec konqueror --profile filemanagement') 
*Confi: (1x1)                # Rest of the buttons still undefined
*Confi: (1x1)
*Confi: (1x1)
*Confi: (1x1)
Module FvwmButtons Confi     # Executes module FvwmButtons with alias 'Confi'

A function is a collection of commands that performs a specific task. FVWM has its own default functions (like StartFunction). Typically, where a function defines a set of rules, they're called a complex function.

Order of Execution. As it is stated in this and this post, the order of execution of the config file is the following:

Commands (as they are found)
StartFunction, InitFunction, RestartFunction
Functions and Modules

For example, if you have in your config file:

AddToFunc StartFunction
+ I Test (Init) Exec exec kontact
Style Kontact StartsOnPage 0 1 0

Kontact will start on Page 0,1,0 despite the command Style is posterior to the function StartFunction. The prefix function and module tells fvwm the type of object. If the prefix is omitted, fvwm will try to match it following this order (fvwm man page):

1.  Match it to one of its internal commands. 
2.  Match it to a function name. 
3.  Match it to a module.

StartUp Applications

FVWM has initialisation functions. StartFunction is executed on startups and restarts. If you have FVWM 2.5.X you can also use StartFunction for Init and Reboot (see this thread). You can add modules and applications to start up with fvwm including them to your ~/.fvwm/config file: In this example, StartFunction is used for Init applications.

AddToFunc    StartFunction
+ I Test (Init) Exec exec kdeinit
+ I Test (Init) Exec exec xmodmap -e "pointer = 3 2 1 4 5"
+ I Test (Init) Exec exec gkrellm2 -g +1+150
+ I Test (Init) Exec exec kontact
+ I Test (Init) Exec exec konsole

You could also define in which desktop/page do you want these applications to appear. For example, we could define that our desktops have a grid of 3x2 pages.

DesktopSize 3x2

Let's now define in which desktop/page we will have our applications:

Style Kontact StartsOnPage 0 1 0
Style Konsole StartsOnPage 0 1 1

Kontact will start on desktop 0, page column1-line0; while konsole will start on desktop 0, page column1-line 1.


The default menus suck. Here's one based on a light GNOME environment, with some games (Linux native, or course). Open up ~/.fvwm/menus for editing:

File: ~/.fvwm/menus
MenuStyle * Hilight3DThickness 2
MenuStyle * BorderWidth 3

DestroyMenu Main
AddToMenu Main "Main" Title
+ "Term" Exec exec xterm
+ ""
+ "Gaim" Exec exec gaim
+ "Epiphany" Exec exec epiphany
+ "Evolution" Exec exec evolution
+ "Rhythmbox" Exec exec rhythmbox

DestroyMenu Games
AddToMenu Games "Games" Title
+ "UT2004" Exec exec /opt/ut2004/ut2004
+ "Neverwinter Nights" Exec exec nwn

DestroyMenu Actions
AddToMenu Actions "Actions" Title
+ "Lock" Exec exec xscreensaver-command -lock
+ "Restart"  Restart
+ "Quit" Quit

Alternatively, there is already a heap of menu definitions supplied by the programs that you install, just that FVWM doesn't know how to read them (yet). The format for these is defined by the Freedesktop standard, and there's a very useful script available from the Fvwm Wiki for creating an automatically generated menu from these definitions.

Even better, with a few modifications this script can be used to create the Icon and MiniIcon styles for the programs defined this way, making it much easier to set up some default styles for your programs.

A sample modified version:

File: ~/.fvwm/script/fvwm-gnome2
#! /bin/sh

# Very hasty and simple script to generate some menus for FVWM from the GNOME directory /usr/share/applications
# Needs bells, whistles, options, flannel, improvements, documentation, kde. Nah.
SYSFILES=`find /usr/share/applications -name *.desktop`
LOCALFILES=`find /usr/local/share/applications -name *.desktop`
        NAME=`basename $FILE .desktop` awk -F= '

/^Name=/ { name=$2 }
/^Name/ { if (!altname) { altname=$2 } }
/^Categories=/ { categories=$2 }
/^Icon=/ { icon=$2 }
/^Exec=/ { run=$2 }

        filename = ENVIRON["NAME"]
        if (!name) { name = altname}
        if (!name) { name = filename}
        if (!run) { run = filename }
        if (!icon) { icon = "/usr/share/pixmaps/mini/gnome-unknown.png" }
        printf("%s:%s:%s:%s:%s\n",  categories, name, filename, icon, run)
}' $FILE
done | sed -e "s/GNOME;//g; s/KDE;//g; s/GTK;//g; s/QT;//g; s/Qt;//g; \
s/Application;//g; s/X-\([A-Za-z-]*\);//g; s/Viewer;//g; \
s/\([A-Za-z-]*;\)\1/\1/g; \
" |sort | awk -F: '
        print "DestroyMenu Gnome2Menu"
        print "AddToMenu Gnome2Menu \"Applications Menu%%mini/gnome-unknown.png%%\" Title"

function build_menu(cat,name,filename,icon,run) {
        if (num > 0) {
        else {
            if (!exists[menu_name]) {
                    printf("AddToMenu %s \"%s%%mini/gnome-unknown.png%%\" Popup %s\n", parent_menu, menu_name, menu_name)
                    printf("DestroyMenu %s\n", menu_name)
                    printf("AddToMenu %s \"%s%%mini/gnome-unknown.png%%\" Title\n", menu_name, menu_name)
        for (i=1; i<num; i++) {
                if (menu_name) {
                        menu_name=menu_name "-" list[i]
                } else {
                        menu_name = list[i]
                if (!exists[menu_name]) {
                        printf("AddToMenu %s \"%s%%mini/gnome-unknown.png%%\" Popup %s\n", parent_menu, list[i], menu_name)
                        printf("DestroyMenu %s\n", menu_name)
                        printf("AddToMenu %s \"%s%%mini/gnome-unknown.png%%\" Title\n", menu_name, menu_name)
                parent_menu = menu_name
        if (list[num] !~ /(.png|.xpm)$/) list[num] = list[num] ".png"
        icon = list[num]
        mini_icon = "mini/" icon
        printf("AddToMenu %s \"%s (%s)%%%s%%\" Exec exec %s\n", menu_name, name, filename, mini_icon, run)
        num=split(run,list," ")
        printf("Style %s* Icon %s, MiniIcon %s\n", list[1], icon, mini_icon)



To include the generated menu in your own menus, you need to read in the output from this file and then include the 'Gnome2Menu' menu that it generates. To do this, open the file ~/.fvwm/menus for editing again, and add to the top:

File: ~/.fvwm/menus
# Read in the auto-generated menu
PipeRead '$[FVWM_USERDIR]/scripts/fvwm-gnome2'

MenuStyle * Hilight3DThickness 2
MenuStyle * BorderWidth 3

AddToMenu "Main" "Main" Title
+ "Term" Exec xterm
+ ""
+ "Gaim" Exec exec gaim
+ "Epiphany" Exec exec epiphany
+ "Evolution" Exec exec evolution
+ "Rhythmbox" Exec exec rhythmbox
# Use the auto-generated menu
+ "Applications" Popup Gnome2Menu
# Reread the menus - will regenerate the auto-generated menu
+ "Refresh Menus" Read $[FVWM_USERDIR]/Menus


Mouse Settings

If you don't specify anything, FVWM will have some default mouse settings, that, well, are minimal and don't work with our menus. Lets fix that.

File: ~/.fvwm/ConfigMouse
Mouse 0         1       A Iconify
Mouse 0         2       A Maximize

Mouse 1         R       A Menu Main
Mouse 2         R       A Menu Games
Mouse 3         R       A Menu Actions

Mouse 1         I       A DeIconify

DestroyFunc DeIconify
AddToFunc DeIconify
+ I       Iconify Off
+ I       ThisWindow (Sticky) PlaceAgain
+ I       ThisWindow (State 2) PlaceAgain
+ I       Raise
+ I       PointerWindow OnEnter

The syntax is: Mouse <button> <clicked where> <modifier> <do what>

<button>: On a three button wheelmouse this can take the form of 0=any, 1=left, 2=middle, 3=right.

<clicked where>: If this is a number it refers to a window button such as 1=raised dash, 2=big square, 4=medium square, 6=dot. Otherwise, R=root window, W=window, T=titlebar, I=icon, S=border

<modifier>: A=any, M=meta(alt), N=none, S=shift, C=ctrl Super_L=winkey

Loading Menus and Mouse

To read in the menus and mouse configs, have the following:

File: ~/.fvwm/.fvwm2rc
read $./Menus
read $./ConfigMouse

From now on, ~/.fvwm/.fvwm2rc will be used only for the most basic of functions. But feel free to change the layout to your liking, as FVWM allows you to configure it just for you.


If you used the automatic menu generation, there are some icons defined for the Icon and MiniIcon style for each program that has a menu entry. These can be used for things like viewing in the taskbar, or as a button at the top of each window, but FVWM needs to know where to look for the icons, and they need to actually be there.

To define the path(s) to look for icons, use the 'ImagePath' directive in your ~/.fvwm/.fvwm2rc file as follows:

File: ~/.fvwm/.fvwm2rc
ImagePath /usr/share/pixmaps:/usr/local/share/pixmaps:${HOME}/.fvwm/icons/personal:+

Multiple search directories can be chained together, and it will use the first instance of a file that matches the specified filename that it finds in the path. The '+' sign at the end indicates that anything that was already defined for the ImagePath should be appended to the end of this listing.

The problem with this is that many icons will not yet be present - or the mmain, fullsize icon will be but the mini-icon version will not. To fix this, you'll need to go and convert each icon in use to include a mini icon.

e.g. As root:

cd /usr/share/pixmaps
mkdir mini
for i in *.{png,xpm}; do convert "$i" -resize 20 "mini/$i"; done

This will create a mini icon in /usr/share/pixmaps/mini of size 20x20 (change it to whatever size you prefer) for every png and xpm format icon in the /usr/share/pixmaps directory.

Likewise, you can use the icons from gnome or kde definitions by copying a 'base' icon to a known location (e.g. your personal directory ${HOME}/.fvwm/icons/personal), then as yourself running the conversion script (which comes from the package imagemagik).

Create as many specific sets of icons as you like, and just add the additional directories to your ImagePath.

Using Icon Styles

Icons can now be included in your menus, and added to the title bar for each program if you wish.

For menus, this is controlled by the MenuStyle ItemFormat option, which shoud be kept with the rest of your MenuStyle options so that it's easy to find (the ~/.fvwm/Menus file if you've followed the earlier instructions).

An example setting would be:

MenuStyle * ItemFormat "|%.5i%.5l%.5i%2.3>%2|"

which gives an item icon, the name of the menu entry, followed by a possible second icon, followed by an arrow if the menu entry opens up a new menu.

If no icon was specified for the menu entry, it just leaves a blank space.

Using icons in the title bar is done through the ButtonStyle <num> MiniIcon option. To set the first button (the left-hand one) of the titlebar to use the MiniIcon defined for the program, add a line to ~/.fvwm/fvwm2rc as follows:

AddToDecor DefaultDecor
+ ButtonStyle 1 MiniIcon -- Flat UseTitleStyle

System Tray

Fvwm does not have a default system tray. Applications that can be "minimized to the tray" usually appear on its own window (see this thread). In case you need a system tray you can choose between system trays like trayer or stalonetray. You can start stalonetray in your StartFuntion:

AddToFunc StartFunction
+ I Schedule 800 Exec exec stalonetray

or have it in your FvwmButtons, as suggested in this thread.


Fvwm does not automount devices, but you can easily create udev rules offering this (and many other) function. There are different examples in the Auto Mount Filesystems of the Gentoo Wiki.

Basic Controls

If you haven't discovered it yet, FVWM allows you to have multiple workspaces arranged into a 3x3 grid (but that's adjustable). This is one of the reasons I love FVWM. You don't have to move your mouse to some control to switch desktops, you just move to the edge of the screen. We're also going to establish some defaults, and our default programs. If you have a lot of programs you like to load on default, you may want to tell FVWM only to load it once. In your StartFunction, you can do:

StartFunction I Test (Init) Exec exec myapp

File: ~/.fvwm/.fvwm2rc
EdgeResistance 100 0
EwmhBaseStruts 0 80 0 45

ImagePath +:/usr/share/icons/Bluecurve/16x16/apps

read $./Menus
read $./ConfigFvwmPager
read $./ConfigMouse
read $./ConfigFvwmTaskBar

*FvwmTaskBarStartMenu: Main

#AddToFunc StartFunction
#+ I Module FvwmPager 0 1:
#+ I Module FvwmWinList * *
+ I Test (Init) Exec exec numlockx
+ I Test (Init) Exec exec xscreensaver

# Styles
Style * MouseFocusClickRaises
Style Fvwm* !Title,  Sticky, WindowListSkip, BorderWidth 0, HandleWidth 0, StaysOnTop, StaysPut, !Handles, !Borders

and Fvwm* will expand to all modules for FVWM. (Although this is potentially annoying (see the Styles section, below)).

The StartFunction is executed everytime FVWM config files are read (restarts). Although with "Test (Init) then only those lines are read; once when FVWM loads.


This information is taken from Thomas Adam
article in Linux Gazzette.

A window is a decorated screen frame containing the graphical interface of a program. The structure of a typical window usually contains the following: Title Bar, Window Buttons and Window Border.

Window Buttons

Fvwm allows up to a maximum of ten buttons on the window titlebar and they can be defined to perform a number of functions. Each button is numbered and seed by Fvwm like this:

| 1 3 5 7 9              Title               0 8 6 4 2 |
|                                                      |

There are two types of buttons that can be defined: vector buttons (used by default) and pixmaps. You can find examples of vector buttons definitions here, and here explains its logic so you can create them. From the vector button examples, the definition of button 1 could be:

ButtonStyle 1 14 20x20@1 20x70@1 70x70@0 70x20@0 20x20@1 60x60@0 60x50@0 60x60@0 50x60@0 60x60@0 60x80@0 80x80@0 80x60@0 60x60@0

For the button to display in the titlebar you must give it a mouse-binding. For example:

Mouse 1 1 A Move

Tells FVWM that if mouse button 1 clicks window button 1 with Any modifier key (like shift or alt) then the window is Moved.

Modular FVWM

Our goal here will be to create a "modular" FVWM. As such, we're just going to create seperate files for each module, which will add itself to the StartFunction.

To include the file, just add a line like the following

File: ~/.fvwm/.fvwm2rc
 read ConfigFvwmPager

Module configuration


See this page.


I get in troubles in my system that use 2 locales: en_GB.UTF-8 for root in order to get English messages with portage and fr_CH.UTF-8 as user. The problem was at I launch FVWM with gdm and at I have a function in my FVWM config that call a bash script that have some locale dependent action (I also have localized menus). By setting the user locale in ~/.bashrc and without any ~/.profile, I get my localized menu in french when using my French locale and the script was running fine, but when shifting to English locale, my menu was still in French and the script was completely confused. The solution was to use the same locale in both ~/.bashrc and ~/.profile.

See also

Retrieved from ""

Last modified: Sat, 30 Aug 2008 07:49:00 +0000 Hits: 25,329