NixOS

https://nixos.org/manual/nixos/unstable
Admin
NixOS is a Linux distribution built on top of the Nix package manager, emphasizing declarative...
Tokens:444,406
Snippets:4,873
Trust Score:10
Update:1 hour ago
Show doc for...
Tokens:
Raw
### Example for process.argv

Source: https://nixos.org/manual/nixos/unstable/

Example value for the command filename and arguments for starting the service. Shows using lib.getExe on the package and passing a flag.

```nix
[ (lib.getExe config.package) "--nobackground" ]
```

--------------------------------

### Start X server with -xkbdir for custom layouts

Source: https://nixos.org/manual/nixos/unstable/

When manually starting the X server, pass -xkbdir /etc/X11/xkb so X can find the custom layout files. Example with xinit.

```bash
$ xinit -- -xkbdir /etc/X11/xkb
```

--------------------------------

### Lemmy quickstart configuration

Source: https://nixos.org/manual/nixos/unstable/

Minimal configuration to start a Lemmy instance with a local database and Caddy reverse proxy. Starts the backend on port 8536 and frontend on port 1234, and initializes Postgres automatically.

```nix
{
  services.lemmy = {
    enable = true;
    settings.hostname = "lemmy.union.rocks";
    database.createLocally = true;
    caddy.enable = true;
  };
}
```

--------------------------------

### Start a login shell in the new NixOS installation with nixos-enter

Source: https://nixos.org/manual/nixos/unstable/

Build and run nixos-enter to start a login shell in the installation mounted at /mnt.

```shell
$ nix-build '<nixpkgs>' -A nixos-enter
# ./result/bin/nixos-enter
```

--------------------------------

### Start window manager manually in ~/.xinitrc

Source: https://nixos.org/manual/nixos/unstable/

Example of starting a window manager (sxhkd and bspwm) when writing your own xinitrc from scratch.

```bash
sxhkd &
 bspwm &
```

--------------------------------

### Quickstart Castopod with Nginx and ACME

Source: https://nixos.org/manual/nixos/unstable/

Starts a public Castopod instance on castopod.example.com. Opens ports 80 and 443, creates a local database, and configures Nginx with ACME and forced SSL. After applying, visit https://castopod.example.com/cp-install to create the superadmin account.

```nix
{
  networking.firewall.allowedTCPPorts = [
    80
    443
  ];
  services.castopod = {
    enable = true;
    database.createLocally = true;
    nginx.virtualHost = {
      serverName = "castopod.example.com";
      enableACME = true;
      forceSSL = true;
    };
  };
}
```

--------------------------------

### Commands for Installing NixOS on /dev/sda

Source: https://nixos.org/manual/nixos/unstable/

Complete installation sequence on a partitioned disk: format filesystems, mount, generate config, edit configuration.nix, install, and reboot. UEFI-only steps are marked with comments.

```bash
# mkfs.ext4 -L nixos -i 8192 /dev/sda1
# mkswap -L swap /dev/sda2
# swapon /dev/sda2
# mkfs.fat -F 32 -n boot /dev/sda3        # (for UEFI systems only)
# mount /dev/disk/by-label/nixos /mnt
# mkdir -p /mnt/boot                      # (for UEFI systems only)
# mount -o umask=077 /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only)
# nixos-generate-config --root /mnt
# nano /mnt/etc/nixos/configuration.nix
# nixos-install
# reboot
```

--------------------------------

### start()

Source: https://nixos.org/manual/nixos/unstable/

Starts the machine. This method is asynchronous — it does not wait for the machine to finish booting.

```APIDOC
## start()

### Description
Starts the machine. This method is asynchronous — it does not wait for the machine to finish booting.

```

--------------------------------

### Basic NixOS test script: start machine, wait for unit, check output

Source: https://nixos.org/manual/nixos/unstable/

Example test script for a virtual machine defined in `nodes.machine`. The `machine` variable is available in the test script. The first line is optional because machines are implicitly started on first action; `t.assertIn` uses assertions from `unittest.TestCase`.

```python
machine.start()
machine.wait_for_unit("default.target")
t.assertIn("Linux", machine.succeed("uname"), "Wrong OS")
```

--------------------------------

### Install NixOS installation tools

Source: https://nixos.org/manual/nixos/unstable/

Installs nixos-generate-config and nixos-install, plus man pages and nixos-enter for chrooting into the NixOS partition. Required before generating configuration or installing.

```bash
$ nix-env -f '<nixpkgs>' -iA nixos-install-tools
```

--------------------------------

### Install Nix package manager (short version)

Source: https://nixos.org/manual/nixos/unstable/

Quick installation of the Nix package manager using the official installer script. After running, source the Nix profile or open a fresh shell to use Nix commands.

```bash
$ curl -L https://nixos.org/nix/install | sh
$ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell
```

--------------------------------

### mkPackageOption with explicit default and example

Source: https://nixos.org/manual/nixos/unstable/

Shows how to provide an explicit default attribute path and an example expression for mkPackageOption. The default is pkgs.ghc, defaultText is "pkgs.ghc", and the example is a literal expression for a Haskell package set.

```nix
lib.mkPackageOption pkgs "GHC"
  {
    default = [ "ghc" ];
    example = "pkgs.haskellPackages.ghc.withPackages (hkgs: [ hkgs.primes ])";
  }
  # is like
  lib.mkOption
  {
    type = lib.types.package;
    default = pkgs.ghc;
    defaultText = lib.literalExpression "pkgs.ghc";
    example = lib.literalExpression "pkgs.haskellPackages.ghc.withPackages (hkgs: [ hkgs.primes ])";
    description = "The GHC package to use.";
  }
```

--------------------------------

### Build and run a QEMU VM

Source: https://nixos.org/manual/nixos/unstable/

Build a virtual machine with the desired configuration and run it. The VM has no data from the host; user accounts may be missing unless mutableUsers is set.

```bash
$ nixos-rebuild build-vm
$ ./result/bin/run-*-vm
```

--------------------------------

### GET /image/process.jpg example request

Source: https://nixos.org/manual/nixos/unstable/

Example request to the image processing endpoint. Creates a 256x256px JPEG thumbnail and applies a gaussian blur of 3.0.

```http
GET /image/process.jpg?src=asdf.png&thumbnail=256&blur=3.0
```

--------------------------------

### Example: NixOS Configuration

Source: https://nixos.org/manual/nixos/unstable/

A sample configuration.nix that imports hardware-configuration.nix, sets the boot loader (GRUB for BIOS or systemd-boot for UEFI), optionally sets fileSystems, and enables the OpenSSH server.

```nix
{ config, pkgs, ... }: {
  imports = [
    # Include the results of the hardware scan.
    ./hardware-configuration.nix
  ];

  boot.loader.grub.device = "/dev/sda";   # (for BIOS systems only)
  boot.loader.systemd-boot.enable = true; # (for UEFI systems only)

  # Note: setting fileSystems is generally not
  # necessary, since nixos-generate-config figures them out
  # automatically in hardware-configuration.nix.
  #fileSystems."/".device = "/dev/disk/by-label/nixos";

  # Enable the OpenSSH server.
  services.sshd.enable = true;
}
```

--------------------------------

### Enable Apache HTTP Server with option definitions

Source: https://nixos.org/manual/nixos/unstable/

Example configuration enabling services.httpd with adminAddr and virtualHosts.documentRoot.

```nix
{ config, pkgs, ... }:

{
  services.httpd.enable = true;
  services.httpd.adminAddr = "alice@example.org";
  services.httpd.virtualHosts.localhost.documentRoot = "/webroot";
}
```

--------------------------------

### Overriding a type check

Source: https://nixos.org/manual/nixos/unstable/

Fully overrides the check function of a type using the '//' operator. The example overrides 'types.str' to only accept strings starting with 'nix'.

```nix
{
  nixThings = mkOption {
    description = "words that start with 'nix'";
    type = types.str // {
      check = (x: lib.hasPrefix "nix" x);
    };
  };
}
```

--------------------------------

### Simple mkPackageOption usage example

Source: https://nixos.org/manual/nixos/unstable/

Shows the result of calling lib.mkPackageOption pkgs "hello" { } as an equivalent lib.mkOption expression. The default is pkgs.hello, defaultText is "pkgs.hello", and description is "The hello package to use."

```nix
lib.mkPackageOption pkgs "hello" { }
  # is like
  lib.mkOption
  {
    type = lib.types.package;
    default = pkgs.hello;
    defaultText = lib.literalExpression "pkgs.hello";
    description = "The hello package to use.";
  }
```

--------------------------------

### Test kernel and initial ramdisk with QEMU

Source: https://nixos.org/manual/nixos/unstable/

Build the initial ramdisk and kernel, then test them with QEMU's `-kernel` and `-initrd` options. The output files are placed in `initrd` and `kernel` directories.

```bash
$ nix-build -A config.system.build.initialRamdisk -o initrd
$ nix-build -A config.system.build.kernel -o kernel
$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
```

--------------------------------

### Enable Timekpr-nExT screen time management

Source: https://nixos.org/manual/nixos/unstable/

Enables the Timekpr-nExT service, which installs the 'timekpr' package and starts the service. Use the 'timekpra' application to configure time limits for users.

```nix
{ services.timekpr.enable = true; }
```

--------------------------------

### Conditional package installation using config

Source: https://nixos.org/manual/nixos/unstable/

Example module that adds packages to environment.systemPackages only if services.xserver.enable is set to true somewhere else. It uses the config argument to access the merged system configuration.

```nix
{ config, pkgs, ... }:

{
  environment.systemPackages =
    if config.services.xserver.enable then
      [
        pkgs.firefox
        pkgs.thunderbird
      ]
    else
      [ ];
}
```

--------------------------------

### Initialize Pleroma database with setup.psql

Source: https://nixos.org/manual/nixos/unstable/

Run this command as the postgres user to create and seed the database using the setup.psql file generated earlier.

```bash
$ sudo -u postgres psql -f setup.psql
```

--------------------------------

### Interactive SSHFS mount with sshfs

Source: https://nixos.org/manual/nixos/unstable/

Mount a remote directory over SFTP interactively after installing the `sshfs` package. No additional server setup is required beyond SSH access. Unmount with `fusermount -u`.

```bash
$ sshfs my-user@example.com:/my-dir /mnt/my-dir
```

```bash
$ fusermount -u /mnt/my-dir
```

--------------------------------

### Enable Portmaster service with minimal configuration

Source: https://nixos.org/manual/nixos/unstable/

Minimal NixOS module configuration to enable the Portmaster application firewall service. The desktop client is installed in the system environment and starts in the background with graphical sessions.

```nix
{
  services.portmaster.enable = true;
}
```

--------------------------------

### Enable Meilisearch service in NixOS configuration

Source: https://nixos.org/manual/nixos/unstable/

Minimal NixOS module configuration to enable the Meilisearch service. Starts the HTTP server on port 7700. Verify with `curl -X GET 'http://localhost:7700/health'`.

```nix
{ services.meilisearch.enable = true; }
```

--------------------------------

### Build custom postgresql-with-plugins using .withPackages in overlay

Source: https://nixos.org/manual/nixos/unstable/

Overlay example that creates a custom PostgreSQL package with plugins using the `.withPackages` function. This is intended for use outside of NixOS.

```nix
self: super: {
  postgresql_custom = self.postgresql_17.withPackages (ps: [
    ps.pg_repack
    ps.postgis
  ]);
}
```

--------------------------------

### Get session status with loginctl session-status

Source: https://nixos.org/manual/nixos/unstable/

Displays detailed information about a specific session, including the user, seat, TTY, service, state, and the processes belonging to the session. The example shows a user logged in on virtual console 3.

```bash
$ loginctl session-status c3
c3 - root (0)
           Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago
          Leader: 2536 (login)
            Seat: seat0; vc3
             TTY: /dev/tty3
         Service: login; type tty; class user
           State: online
          CGroup: name=systemd:/user/root/c3
                  ├─ 2536 /nix/store/10mn4xip9n7y9bxqwnsx7xwx2v2g34xn-shadow-4.1.5.1/bin/login --
                  ├─10339 -bash
                  └─10355 w3m nixos.org
```

--------------------------------

### Package option definitions

Source: https://nixos.org/manual/nixos/unstable/

Example of using pkgs to set environment.systemPackages and services.postgresql.package.

```nix
{
  environment.systemPackages =
    [ pkgs.thunderbird
      pkgs.emacs
    ];

  services.postgresql.package = pkgs.postgresql_14;
}
```

--------------------------------

### Build and run Emacs with packages

Source: https://nixos.org/manual/nixos/unstable/

Commands to build the Emacs derivation and launch it with `-q` to verify the installed packages. After running, use `M-x package-initialize` and test packages like the zerodark theme.

```shell
$ nix-build emacs.nix
$ ./result/bin/emacs -q
```

--------------------------------

### Custom configuration.nix for kexec with netboot-minimal.nix

Source: https://nixos.org/manual/nixos/unstable/

Defines a custom system closure to kexec into instead of the default installer image. Must import `netboot-minimal.nix` (or `netboot-base.nix`) from the installer/netboot module path. The example enables OpenSSH and adds a root authorized key.

```nix
{ modulesPath, ... }:
{
  imports = [ (modulesPath + "/installer/netboot/netboot-minimal.nix") ];

  services.openssh.enable = true;
  users.users.root.openssh.authorizedKeys.keys = [ "my-ssh-pubkey" ];
}
```

--------------------------------

### Generate example Mautrix-Whatsapp configuration for migration

Source: https://nixos.org/manual/nixos/unstable/

Run this command to generate the example configuration for Mautrix-Whatsapp. Compare it with the migrated configuration at /var/lib/mautrix-whatsapp/config.yaml to update your NixOS module configuration.

```shell
nix-shell -p mautrix-whatsapp --run "mautrix-whatsapp -c example.yaml -e"
```

--------------------------------

### Plausible NixOS configuration

Source: https://nixos.org/manual/nixos/unstable/

Example NixOS module configuration for deploying Plausible. Requires a secret key generated with openssl and optionally an admin user with a bcrypt password hash. If adminUser is not declared, an unauthenticated first-launch setup wizard is shown, which is a security risk.

```nix
{
  services.plausible = {
    enable = true;
    server = {
      baseUrl = "http://analytics.example.org";
      # secretKeybaseFile is a path to the file which contains the secret generated
      # with openssl as described above.
      secretKeybaseFile = "/run/secrets/plausible-secret-key-base";
      # With an admin user seeded (below), registration can be locked down
      # so only invited users (or nobody) can create further accounts.
      disableRegistration = "invite_only";
    };
    # If you do not declare `adminUser`, Plausible shows an unauthenticated
    # "first launch" setup wizard where anybody reaching the instance can create
    # the first admin account. That may be convenient, but is also a security
    # risk if somebody else uses it before you do.
    adminUser = {
      email = "admin@analytics.example.org";
      # passwordHashFile is a path to a file containing the bcrypt hash of the
      # admin user's password, e.g. generated with `mkpasswd -m bcrypt`.
      passwordHashFile = "/run/secrets/plausible-admin-password-hash";
    };
  };
}
```

--------------------------------

### Example partition schemes for NixOS on /dev/sda (UEFI)

Source: https://nixos.org/manual/nixos/unstable/

Partitions /dev/sda with a GPT label for UEFI: root, swap, and ESP partitions, with the ESP marked as bootable.

```bash
# parted /dev/sda -- mklabel gpt
# parted /dev/sda -- mkpart root ext4 512MB -8GB
# parted /dev/sda -- mkpart swap linux-swap -8GB 100%
# parted /dev/sda -- mkpart ESP fat32 1MB 512MB
# parted /dev/sda -- set 3 esp on
```

--------------------------------

### Declarative package installation in configuration.nix

Source: https://nixos.org/manual/nixos/unstable/

Add a package to the system by setting environment.systemPackages in configuration.nix. The example enables Mozilla Thunderbird; the package will be built or downloaded when running nixos-rebuild switch. Some packages may require additional global configuration such as D-Bus or systemd service registration.

```nix
{ environment.systemPackages = [ pkgs.thunderbird ]; }
```

--------------------------------

### Example configData with text and source files

Source: https://nixos.org/manual/nixos/unstable/

Example configuration for the `configData` option, defining a text-based configuration file and a source file. The `path` sub-option provides the actual location where the file will be available.

```nix
{
  "server.conf" = {
    text = ''
      port = 8080
      workers = 4
    '';
  };
  "ssl/cert.pem" = {
    source = ./cert.pem;
  };
}
```

--------------------------------

### Simple ephemeral Yggdrasil node configuration

Source: https://nixos.org/manual/nixos/unstable/

Annotated example of a simple Yggdrasil node configuration. With persistentKeys disabled, the NixOS module generates new keys and a new IPv6 address each time it starts. Peers are specified as TCP addresses; public peers can be found at the linked repository.

```nix
{
  services.yggdrasil = {
    enable = true;
    persistentKeys = false;
    # The NixOS module will generate new keys and a new IPv6 address each time
    # it is started if persistentKeys is not enabled.

    settings = {
      Peers = [
        # Yggdrasil will automatically connect and "peer" with other nodes it
        # discovers via link-local multicast announcements. Unless this is the
        # case (it probably isn't) a node needs peers within the existing
        # network that it can tunnel to.
        "tcp://1.2.3.4:1024"
        "tcp://1.2.3.5:1024"
        # Public peers can be found at
        # https://github.com/yggdrasil-network/public-peers
      ];
    };
  };
}
```

--------------------------------

### Generate example Mautrix-Signal configuration for migration

Source: https://nixos.org/manual/nixos/unstable/

Run this command to generate the example configuration for Mautrix-Signal. Compare it with the migrated configuration at /var/lib/mautrix-signal/config.yaml to update your NixOS module configuration.

```shell
nix-shell -p mautrix-signal --run "mautrix-signal -c example.yaml -e"
```
Tokens:
Raw