Skip to main content
Version: 2.1

SomeWM Documentation

SomeWM 2.1 is a programmable Wayland compositor built on AwesomeWM's Lua configuration model. Its widget system lets you build the desktop itself: bars, launchers, popups, titlebars and notifications. Make a clock open a calendar, build a control panel for your system, or write your own window layout. Start with the supplied configuration and add what you need.

Start here​

Starting pointRead next
I want to try SomeWMRun it in a window without logging out, or install and launch it.
I have a running session and want to build somethingBuild a clock widget. Create a Lua module, see it on screen, add interaction, then put it in your bar.
I have a SomeWM 2.0 configurationUpgrade to 2.1, including how to port custom widgets.
I have an AwesomeWM configurationMigrate from AwesomeWM and check the widget changes.

Build your desktop​

Start with configuration basics if you have not edited rc.lua before. Then follow the widget path:

  1. Build a clock widget: a complete example you can see and interact with.
  2. Build a wibar: place widgets alongside tags, tasks and the system tray.
  3. Create a custom widget: add your own methods and state, write a Clay description, or display custom Cairo artwork.

Keybindings, Theme and Carousel cover other parts of the desktop. You do not need to read the renderer documentation before building widgets.

Solve a specific task​

Update widgets from timers and commands, animate them, or write a client layout. The How-To Guides section in the sidebar lists configuration tasks such as input devices, notifications and multiple monitors.

Reference​

PageCovers
Lua Librariesevery library, with upstream links
awful, wibox, beautiful, naughty, gearsthe libraries
somewm-clientthe IPC command line
Key Nameskeys and modifiers
Compatibility referenceplatform differences and compatibility limits

Concepts​

Versions​

2.1 is the newest release. The version switcher has 2.2 in development, 2.0, and 1.4, which mirrors AwesomeWM master and is maintained indefinitely. The AwesomeWM apidoc covers inherited APIs not yet documented here.