Installation

Want to try first?

You can run a sandboxed nested SomeWM inside your current Wayland or X11 session without logging out. Install the binary, then follow the Try SomeWM Without Logging Out tutorial. Your daily-driver desktop is untouched.

Dependencies

wlroots

SomeWM is tightly coupled to wlroots 0.19. Meson fetches it automatically as a subproject during the build.

Arch Linux

From the AUR (recommended)

yay -S somewm-git
# or with paru:
paru -S somewm-git

This installs somewm and all dependencies. After installation, skip directly to Launch.

Manual Build

If you prefer to build from source:

# Required dependencies
# Note: lua51-lgi is required for LuaJIT (the default Lua for SomeWM)
sudo pacman -S \
    luajit \
    lua51-lgi \
    cairo \
    pango \
    gdk-pixbuf2 \
    wayland-protocols \
    libinput \
    libxkbcommon

# Optional: XWayland support
sudo pacman -S xorg-xwayland libxcb

Debian/Ubuntu

# Required dependencies
sudo apt install \
    meson \
    luajit \
    lua-lgi \
    libcairo2-dev \
    libpango1.0-dev \
    libgdk-pixbuf-2.0-dev \
    libwayland-dev \
    wayland-protocols \
    libdrm-dev \
    libdbus-1-dev \
    libinput-dev \
    libxkbcommon-dev \
    libxcb-util-dev

# Optional: XWayland support
sudo apt install \
    xwayland \
    libxcb1-dev \
    libxcb-icccm4-dev \
    libxcb-composite0-dev \
    libxcb-ewmh-dev \
    libxcb-res0-dev

Fedora

# Required dependencies
sudo dnf install \
    meson \
    luajit \
    luajit-devel \
    lua-lgi \
    cairo-devel \
    pango-devel \
    gdk-pixbuf2-devel \
    wayland-devel \
    wayland-protocols-devel \
    libdrm-devel \
    dbus-devel \
    glib2-devel \
    libinput-devel \
    libxkbcommon-devel

# Optional: XWayland support
sudo dnf install \
    xorg-x11-server-Xwayland \
    xorg-x11-server-Xwayland-devel \
    libxcb-devel \
    xcb-util-wm-devel \
    xcb-util-renderutil-devel

NixOS

A default.nix is provided for building on NixOS:

nix-build
./result/bin/somewm

The included derivation sets up LGI and GI_TYPELIB_PATH automatically. For custom configurations or third-party Lua libraries, see the NixOS section below.

Build and Install

git clone https://github.com/trip-zip/somewm
cd somewm
make
sudo make install

The build will verify that LGI is correctly installed for your Lua version. If the check fails, you'll see instructions for which package to install.

LGI Troubleshooting

SomeWM requires LGI (Lua GObject Introspection bindings) for widget rendering. The LGI package must match your Lua version.

Lua Version	Arch Linux	Debian/Ubuntu	Fedora
LuaJIT (default)	lua51-lgi	lua-lgi	lua-lgi
Lua 5.4	lua-lgi	lua-lgi	lua-lgi

If you have the wrong package, you'll see:

module 'lgi' not found

For custom LGI locations, use the -L (or --search) flag:

somewm -L /usr/lib/lua/5.1

NixOS Details

GI_TYPELIB_PATH and Third-Party Libraries

On NixOS, GObject Introspection typelibs are isolated in /nix/store rather than system paths. The default.nix sets up GI_TYPELIB_PATH with common typelibs (pango, gdk-pixbuf, glib, gtk3).

If you use third-party Lua libraries (like bling), they may require additional typelibs. For example, bling's app_launcher widget requires GTK3 for icon theme lookups.

To add additional typelibs when packaging SomeWM, extend the wrapper:

postFixup = ''
  wrapProgram $out/bin/somewm \
    --prefix GI_TYPELIB_PATH : "${pkgs.gtk3}/lib/girepository-1.0" \
    --prefix GI_TYPELIB_PATH : "${pkgs.networkmanager}/lib/girepository-1.0" \
    # Add more as needed for your Lua libraries
'';

Extra Lua Modules

To add additional Lua modules (like luafilesystem):

let
  luaEnv = pkgs.luajit.withPackages (ps: with ps; [
    lgi
    luafilesystem  # Add extra modules here
  ]);
in
# ... use luaEnv in buildInputs and wrapper

Uninstallation

# Remove installed files
sudo make uninstall

# Remove build directory
make clean

Next Steps

Once installed, proceed to Launch to run SomeWM for the first time.