Skip to content
Simple devilspie-like program for window manipulation, with Lua.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Create FUNDING.yml Jun 26, 2019
debian New debian package Dec 18, 2018
samples Add support for window_role(). Aug 18, 2014
.gitignore Fixed spelling errors. Jul 26, 2014
LICENSE Added explicit GPL-2 license. Jul 21, 2014
Makefile Link against xrandr Dec 13, 2018 Add un- bottom function Jun 5, 2019
bindings.h Add un- bottom function Jun 5, 2019
kpie.1 Install manpage for kpie. Jul 26, 2014
kpie.c Formatted code consistently Feb 15, 2018
kpie.lua Export VERSION and CONFIG to Lua. Jul 21, 2014


KPie is a simple window manipulation tool, modeled after devil's pie, with a Lua-based configuration file.

Usage is:

 kpie [options] [lua-config-file.lua]

Options are currently limited to:

--config   - Explicitly specify a configuration file.
--debug    - Show debugging information.
--single   - Process each window once, then exit.
--version  - Show the version number.


A single Lua configuration file will be parsed and executed for every window on your system, including invisible windows, and windows in different workspaces/virtual-desktops.

Unless you're running kpie --single then the configuration file will be invoked for each window that is opened in the future, until you terminate kpie.

By default kpie looks for ~/.kpie.lua, but you may choose another file when you start kpie via:

$ kpie ~/.config/kpie.lua

As noted the configuration file is Lua with the addition of some window-related primitives. To give you a flavour this is a sample configuration file:

-- If Xine is launched it should be "always on top"
if ( window_class() == "xine" ) then

-- The xlogo program is so cool it should be visible on all
-- workspaces
if ( window_title() == "xlogo" ) then

The kpie.lua sample configuration file contains this code, as well as some more examples of Lua scripting. You can find more specialized example configuration files included in the samples/ directory.

The key thing to understand is that the same configuration file will be invoked for every window on your system, on the basis that you'll limit your actions to specific windows via the matching options.

For example if you had a configuration file which read merely "maximize()" your desktop would become very odd, as all the windows would be maximized, including your panel(s).

Configuration Generator

Included within the repository is a sample configuration file samples/dump.lua which is designed to be a helpful starting point if you wish to script the manipulation of your windows.

Simply run:

$ ./kpie ./samples/dump.lua

This will output chunks of config which you can edit or save:

-- Screen width : 1920
-- Screen height: 1080
if ( ( window_title() == "feeds" ) and
     ( window_class() == "Pidgin" ) ) then
        size(1438,1023 )
if ( ( window_title() == "Buddy List" ) and
     ( window_class() == "Pidgin" ) ) then
     xy(1438,0 )
     size(482,1023 )

As you can see this has iterated over all existing windows, and shown you their current state - this is perfect if you wish to reproduce a complex layout interactively.


You can install binary packages for Debian GNU/Linux from the authors repository:

If you prefer to build from source you can do so providing you have the dependencies installed. Beyond the necessities, a compiler and make, you'll need:

  • libglib2.0-dev
  • libgtk2.0-dev
  • liblua5.1-0-dev
  • libwnck-dev
  • libx11-dev
  • x11proto-core-dev

Upon a Debian GNU/Linux system these may be installed via:

  sudo apt-get install libglib2.0-dev libgtk2.0-dev libwnck-dev libx11-dev liblua5.1-0-dev x11proto-core-dev

With the dependencies in-place you should be able to compile the binary by running:


If you're building from a git checkout, rather than a named release, you'll need to run this instead:

 autoreconf --install


The following primitives are available:

  • Information
    • window_title - Get the title of the new window.
    • window_type - Get the type of the window.
    • window_application - Get the application which created the window.
    • window_class - Get the class of the new window.
    • window_id - Get the ID of the new window.
      • This may be empty.
    • window_xid - Get the XID of the new window.
      • This may be empty.
    • window_pid - Get the PID of the new window.
      • This may be zero on error.
    • window_role - Get the role of the new window, via WM_WINDOW_ROLE.
      • This may return an empty string.
    • screen_height - Get the size of the screen.
    • screen_width - Get the size of the screen.
  • Depth
    • activate - Make the window appear in the foreground and give focus.
    • above - Make the window "always on top".
    • below - Remove the "always on top" flag.
    • bottom - Make the window "always below".
    • unbottom - Remove the "always below" flag.
  • Max/Min
    • maximize - Maximize the window.
    • maximize_horizontally - Maximize horizontally.
    • maximize_vertically - Maximize vertically.
    • fullscreen - Make the window "fullscreen".
    • focus - Focus the window.
    • is_focussed - Is the window focussed?
    • is_maximized - Is the window maximized?
    • is_fullscreen - Is the window fullscreen?
  • Workspace
    • pin - Pin on all workspaces.
    • unpin - Don't pin on all workspaces.
  • Movement
    • xy - Get/Set the X/Y coordinates of a window.
    • size - Get/Set the width/height of a window.
  • Workspaces
    • activate_workspace - Change to the given workspace/virtual-desktop.
    • workspace - Get/set the workspace the window is active on.
      • The return value may be -1 if the window is pinned, or invisible.
    • workspaces - Get/set the number of workspaces/virtual-desktops.
  • Misc
    • decoration - Set/Unset the decorations for the window.
    • exists - Does the given file/directory exist?
    • kill - Close the window, forcibly.
    • pointer - Get/Set the position of the mouse pointer.
    • readdir - Read the contents of a directory.
  • Variables
    • DEBUG will be declared as a boolean false value, unless you launch kpie with the --debug flag.
      • This can be used to control whether you output debugging information.
    • CONFIG will be defined as the path to the configuration file loaded.
    • VERSION will be an integer containing the kpie release.

Some of these primitives are documented in the sample-scripts.


You can’t perform that action at this time.