---
id: liminalOS-docs
aliases: []
tags:
  - nixos
  - nixpkgs
  - liminalos
  - linux
title: Documentation for liminalOS system distribution
---

This is documentation for the [liminalOS system
distribution](https://github.com/youwen5/liminalOS), a Linux distribution built
on [NixOS](https://nixos.org).

The goal of liminalOS is to provide an opinionated desktop environment and
system for those too lazy to spend 100 hours ricing their NixOS system.

To that end, a NixOS module and home manager module are provided such that it
is possible to configure an entire operating system powered by a riced out
desktop environment built on Hyprland in a few lines. These modules come with
verified versions of all of the other flake input modules that compose
liminalOS, so that you don't have to manage and version Home Manager, `stylix`,
`agenix`, etc yourself.

Central to this system is the `liminalOS` option that is added to both home
manager and NixOS. It is designed to be used alongside a very minimal NixOS and
Home Manager configuration to define the entire liminalOS system.

You only need to set up basic things like a minimal `flake.nix`,
`configuration.nix`, and `home.nix`, where you need only set up a basic user
(in both NixOS and HM) and boot loader configuration. The rest of the higher
level system features will be handled by the `liminalOS` abstraction.

Something like this is sufficient to bootstrap a liminalOS system. It can be
dropped into any existing NixOS system and be used alongside an existing
configuration.

```nix
# file: configuration.nix
{
  liminalOS = {
    config.allowUnfree = true;
    defaultEditor = pkgs.helix;
    formFactor = "desktop";
    theming = {
      # place your desired wallpaper in your configuration repo and watch your
      # system theme itself
      wallpaper = ./wallpaper.jpg;
    };
    system.graphics.nvidia.enable = true;
    extras.gaming.enable = true;
  };

  # Set up a user
  users.users.default-user = {
    isNormalUser = true;
    description = "Default liminalOS user!";
    extraGroups = [
      "networkmanager"
      "wheel"
    ];
    shell = pkgs.fish;
  };

  home-manager.users.default-user = {
    # in this simple example, the content of ./home.nix is an import of the
    # liminalOS home manager module
    imports = [ ./home.nix ];
  };
  home-manager.extraSpecialArgs = { inherit inputs; };

  # Set your time zone
  time.timeZone = "America/Los_Angeles";

  # Bootloader and kernel.
  boot = {
    loader = {
      efi.canTouchEfiVariables = true;
      timeout = 15;
      systemd-boot = {
        enable = true;
      };
    };
  };
}
```

The recommended way to start using liminalOS is to first install NixOS and then
install liminalOS over it. It is trivially possible in theory to generate
liminalOS installer ISOs but this has not yet been developed. Hackers welcome
to try!

You can generate a basic set of NixOS configuration files that deploy liminalOS
using:

```bash
nix flake init -t github:youwen5/liminalOS
```

Make sure you read the comments and edit the desired options before
`nixos-rebuild`! At the very least, you should set your hostname and username.

## Full liminalOS module options

These are all of the available options set by `liminalOS`, automatically
generated from liminalOS' modules. Keep in mind that many of these are enabled
automatically when `liminalOS.enable` is set to true, but they are still
available for fine-grained customization.