A NixOS/home-manager flake providing a Wayland-focused desktop environment with Hyprland, Sway, SwayFX, and Scroll support.
Warning
This project is not done and is still alpha; it will contain bugs.
Minima is a Home Manager module. Home Manager is required, regardless of how you use minima:
- On a non-NixOS distro, minima runs as a standalone Home Manager configuration on top of an already-installed window manager.
- On NixOS, minima is a NixOS module that installs the window manager and passes system-level options down to Home Manager, which actually manages all of your config files, the QuickShell panel, styling, and shell setup.
You also need a window manager — Hyprland (the default), Sway,
SwayFX, or Scroll. Select it with minima.<wm>.enable
hyprland defaults to true with the dwindle layout.
{
inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
inputs.home-manager = {
url = "github:nix-community/home-manager";
inputs.nixpkgs.follows = "nixpkgs";
};
inputs.minima = {
url = "github:Poellebob/minima-shell";
inputs.nixpkgs.follows = "nixpkgs";
};
outputs = { self, nixpkgs, home-manager, minima, ... }: {
homeConfigurations."your-username" = home-manager.lib.homeManagerConfiguration {
pkgs = nixpkgs.legacyPackages.x86_64-linux;
modules = [
minima.homeModules.default
{
home.stateVersion = "25.11";
minima = {
enable = true;
hyprland.enable = true; # default; or sway.enable / scroll.enable
shell.enable = true;
theming.enable = true;
darkTheme = true;
wallpaper.engineEnabled = true;
panel.alwaysVisible = true;
vim.enable = true;
};
}
];
};
}
}This expects the selected window manager to already be installed on your system. The NixOS module installs the window manager for you based on which one is enabled.
{
inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
inputs.home-manager = {
url = "github:nix-community/home-manager";
inputs.nixpkgs.follows = "nixpkgs";
};
inputs.minima = {
url = "github:Poellebob/minima-shell";
inputs.nixpkgs.follows = "nixpkgs";
};
outputs = { self, nixpkgs, home-manager, minima, ... }: {
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
home-manager.nixosModules.home-manager
minima.nixosModules.minima
{
# System-level: installs & wraps the window manager, passes options
# down to home-manager via sharedModules.
minima = {
enable = true;
sway.enable = true; # or hyprland.enable (default) / scroll.enable
enableNvidia = false;
};
home-manager.users."your-username" = {
imports = [
minima.homeModules.default
];
home.stateVersion = "25.11";
minima = {
enable = true;
shell.enable = true;
theming.enable = true;
darkTheme = true;
wallpaper.engineEnabled = true;
panel.alwaysVisible = true;
vim.enable = true;
};
};
}
];
};
};
}outputs = { self, ... }: {
homeModules.minima = ...; # Home Manager module
homeModules.default = ...; # alias for homeModules.minima
nixosModules.minima = ...; # NixOS module
nixosModules.default = ...; # alias for nixosModules.minima
}All configuration options are documented in OPTIONS.md.
- Hyprland / Sway / SwayFX / Scroll — pick your window manager with
minima.hyprland.enable,minima.sway.enable(+minima.sway.fx), orminima.scroll.enable; Hyprland layouts include dwindle, master, scrolling, and hy3 - QuickShell panel & launcher — animated bar, app launcher with qalc, clipboard manager, wallpaper engine support
- Session as systemd units — panel and helper daemons run as user units started by the compositor at startup, so rebuilds apply without relogging
- Material you theming — matugen-rendered colors using a seed color, applied to the panel, launcher, and Sway
- KDE-style styling — Breeze cursor/GTK/Qt theming, Papirus icons,
kdeglobals - Shell setup — zsh, starship, eza, fzf, zoxide, bat, ripgrep, lazygit
- Neovim via NixVim — batteries-included editor with LSP, completion, formatting, and linting
- Extra packages — add anything with
minima.extraPackages - NVIDIA support — flip on
minima.enableNvidiafor proprietary driver handling - Desktop integration — XDG portals, desktop menus, Dolphin-adjacent KDE packages
Keybindings use common modifier names that work across all window managers:
| Modifiers |
|---|
Main |
Shift |
Ctrl |
Alt |
minima.keybinds = {
session.launcher = [ "Main" "Space" ];
custom = [
{ exec = "firefox"; bind = [ "Main" "B" ]; }
{ exec = "dolphin"; bind = [ "Main" "E" ]; }
];
};All built-in bindings are configurable through minima.keybinds; set a binding
to [] to disable it. Main + Return opens Kitty while minima.terminal.enable
is enabled. minima.keybinds.custom adds executable or raw compositor bindings.
hy3 actions only apply if the layout is hy3
| Keybind | Action (Hyprland) | Action (Sway) | Action (Scroll) |
|---|---|---|---|
Main + Return |
Open terminal | Open terminal | Open terminal |
Main + q |
Kill focused window | Kill focused window | Kill focused window |
Main + e |
Open file manager | Open file manager | Open file manager |
Main + b |
Open browser | Open browser | Open browser |
Main + Space |
Toggle floating | Toggle floating | Toggle floating |
Main + f |
Toggle fullscreen | Toggle fullscreen | Toggle fullscreen |
Main + Shift + s |
Pin (sticky) | Toggle sticky | Toggle sticky |
Main + Alt + Delete |
Lock screen (swaylock) | Lock screen (swaylock) | Lock screen (swaylock) |
Main + v |
Open clipboard manager | Open clipboard manager | Open clipboard manager |
Main + d |
Open app launcher | Open app launcher | Open app launcher |
Main + Shift + c |
Reload config | Reload config | Reload config |
Main + Alt + l |
hy3: toggle tab group | Tabbed layout | Set window height to 100% |
Main + Alt + h |
hy3: toggle tab group | Stacking layout | Set window height to 50% |
Main + Alt + j |
hy3: vertical split | Split vertical | Move window into column on left |
Main + Alt + k |
hy3: horizontal split | Split horizontal | Move window into column on right |
Main + Shift + a |
toggle split | Split toggle | Direction mode |
Main + a |
hy3: focus parent | Focus parent | - |
Main + Ctrl + a |
hy3: focus child | Focus child | - |
Main + Escape |
hy3: untab group | Default layout | - |
Main + Tab |
hy3: next tab | - | Workspace overview |
Main + Shift + - |
Move to scratchpad | - | Move to scratchpad |
Main + - |
Toggle scratchpad | - | Show scratchpad |
XF86PowerOff |
Open logout menu | Open logout menu | Open logout menu |
| Keybind | Action |
|---|---|
$mod + 1-9, 0 |
Switch to workspace 1-10 |
$mod + Shift + 1-0 |
Move window to workspace |
$mod + Ctrl + Right |
Next workspace |
$mod + Ctrl + Left |
Previous workspace |
| Keybind | Action |
|---|---|
$mod + H |
Focus left |
$mod + L |
Focus right |
$mod + K |
Focus up |
$mod + J |
Focus down |
| Keybind | Action |
|---|---|
$mod + Ctrl + H |
Move window left |
$mod + Ctrl + L |
Move window right |
$mod + Ctrl + K |
Move window up |
$mod + Ctrl + J |
Move window down |
| Keybind | Action |
|---|---|
$mod + Shift + H |
Shrink width 100px |
$mod + Shift + L |
Grow width 100px |
$mod + Shift + K |
Shrink height 100px |
$mod + Shift + J |
Grow height 100px |
| Keybind | Action |
|---|---|
Print |
Screenshot selection → clipboard |
Shift + Print |
Screenshot fullscreen → clipboard |
$mod + Print |
Screenshot selection → edit in swappy |
$mod + Shift + Print |
Screenshot fullscreen → edit in swappy |
| Keybind | Action |
|---|---|
$mod + LMB drag |
Move window |
$mod + RMB drag |
Resize window |
$mod + MMB |
Kill focused window |
| Keybind | Action |
|---|---|
XF86AudioRaiseVolume |
Volume up 5% |
XF86AudioLowerVolume |
Volume down 5% |
XF86AudioMute |
Toggle mute |
XF86AudioMicMute |
Toggle mic mute |
XF86MonBrightnessUp |
Brightness up 10% |
XF86MonBrightnessDown |
Brightness down 10% |
XF86AudioNext |
Next track |
XF86AudioPrev |
Previous track |
XF86AudioPlay/Pause |
Play/Pause |
- OPTIONS.md - All configuration options and how to use them