# Overview

> NixOS manual from NixOS/nixpkgs on master (nixos/doc/manual).

## [Overview](https://docharvest.github.io/docs/nixos/)

Contents

nixos

Overview

NixOS

Overview

[Moved to ./contributing-to-this-manual.chapter.md](./contributing-to-this-manual.chapter.md). Link:

[https://nixos.org/manual/nixos/unstable/#chap-contributing](https://nixos.org/manual/nixos/unstable/#chap-contributing)

## [Administration {#ch-running}](https://docharvest.github.io/docs/nixos/administration/running/)

Contents

nixos

Administration {#ch-running}

NixOS

Administration {#ch-running}

This chapter describes various aspects of managing a running NixOS system, such as how to use the {command}`systemd` service manager.

```
service-mgmt.chapter.md
rebooting.chapter.md
user-sessions.chapter.md
control-groups.chapter.md
logging.chapter.md
system-state.chapter.md
cleaning-store.chapter.md
containers.chapter.md
troubleshooting.chapter.md
```

## [Configuration {#ch-configuration}](https://docharvest.github.io/docs/nixos/configuration/configuration/)

Contents

nixos

Configuration {#ch-configuration}

NixOS

Configuration {#ch-configuration}

This chapter describes how to configure various aspects of a NixOS machine through the configuration file {file}`/etc/nixos/configuration.nix`. As described in [](#sec-changing-config), changes to this file only take effect after you run {command}`nixos-rebuild`.

```
config-syntax.chapter.md
package-mgmt.chapter.md
user-mgmt.chapter.md
file-systems.chapter.md
x-windows.chapter.md
wayland.chapter.md
gpu-accel.chapter.md
xfce.chapter.md
networking.chapter.md
linux-kernel.chapter.md
subversion.chapter.md
```

```
@MODULE_CHAPTERS@
```

```
profiles.chapter.md
mattermost.chapter.md
kubernetes.chapter.md
```

## [Development {#ch-development}](https://docharvest.github.io/docs/nixos/development/development/)

Contents

nixos

Development {#ch-development}

NixOS

Development {#ch-development}

This chapter describes how you can modify and extend NixOS.

```
sources.chapter.md
writing-modules.chapter.md
building-parts.chapter.md
bootspec.chapter.md
what-happens-during-a-system-switch.chapter.md
writing-documentation.chapter.md
nixos-tests.chapter.md
developing-the-test-driver.chapter.md
testing-installer.chapter.md
modular-services.md
```

## [Modular Services {#modular-services}](https://docharvest.github.io/docs/nixos/development/modular-services/)

Contents

nixos

Modular Services {#modular-services}

NixOS

Modular Services {#modular-services}

Status: in development. This functionality is new in NixOS 25.11, and significant changes should be expected. We'd love to hear your feedback in [https://github.com/NixOS/nixpkgs/pull/372170](https://github.com/NixOS/nixpkgs/pull/372170)

Traditionally, NixOS services were defined using sets of options _in_ modules, not _as_ modules. This made them non-modular, resulting in problems with composability, reuse, and portability.

A configuration management framework is an application of `evalModules` with the `class` and `specialArgs` input attribute set to particular values. NixOS is such a configuration management framework, and so are [Home Manager](https://github.com/nix-community/home-manager) and [`nix-darwin`](https://github.com/nix-darwin/nix-darwin).

The service management component of a configuration management framework is the set of module options that connects Nix expressions with the underlying service (or process) manager. For NixOS this is the module wrapping [`systemd`](https://systemd.io/), on `nix-darwin` this is the module wrapping [`launchd`](https://en.wikipedia.org/wiki/Launchd).

A _modular service_ is a [module](https://nixos.org/manual/nixpkgs/stable/index.html#module-system) that defines values for a core set of options declared in the service management component of a configuration management framework, including which program to run. Since it's a module, it can be composed with other modules via `imports` to extend its functionality.

NixOS provides two options into which such modules can be plugged:

-   `system.services.<name>`
-   an option for user services (TBD)

Crucially, these options have the type [`attrsOf`](#sec-option-types-composed) [`submodule`](#sec-option-types-submodule). The name of the service is the attribute name corresponding to `attrsOf`.

The `submodule` is pre-loaded with two modules:

-   a generic module that is intended to be portable
-   a module with systemd-specific options, whose values or defaults derive from the generic module's option values.

So note that the default value of `system.services.<name>` is not a complete service. It requires that the user provide a value, and this is typically done by importing a module. For example:

```
{
  system.services.my-service-instance = {
    imports = [ pkgs.some-application.services.some-service-module ];
    foo.settings = {
      # ...
    };
  };
}
```

## Portability {#modular-service-portability}

It is possible to write service modules that are portable. This is done by either avoiding the `systemd` option tree, or by defining process-manager-specific definitions in an optional way:

```
{
  config,
  options,
  lib,
  ...
}:
{
  _class = "service";
  config = {
    process.argv = [ (lib.getExe config.foo.program) ];
  }
  // lib.optionalAttrs (options ? systemd) {
    # ... systemd-specific definitions ...
  };
}
```

This way, the module can be loaded into a configuration manager that does not use systemd, and the `systemd` definitions will be ignored. Similarly, other configuration managers can declare their own options for services to customize.

## Composition and Ownership {#modular-service-composition}

Compared to traditional services, modular services are inherently more composable, by virtue of being modules and receiving a user-provided name when imported. However, composition can not end there, because services need to be able to interact with each other. This can be achieved in two ways:

1.  Users can link services together by providing the necessary NixOS configuration.
2.  Services can be compositions of other services.

These aren't mutually exclusive. In fact, it is a good practice when developing services to first write them as individual services, and then compose them into a higher-level composition. Each of these services is a valid modular service, including their composition.

## Migration {#modular-service-migration}

Many services could be migrated to the modular service system, but even when the modular service system is mature, it is not necessary to migrate all services. For instance, many system-wide services are a mandatory part of a desktop system, and it doesn't make sense to have multiple instances of them. Moving their logic into separate Nix files may still be beneficial for the efficient evaluation of configurations that don't use those services, but that is a rather minor benefit, unless modular services potentially become the standard way to define services.

## Writing and Reviewing a Modular Service {#modular-service-review}

A typical service module consists of the following:

For more details, refer to the contributor documentation in [`nixos/README-modular-services.md`](https://github.com/NixOS/nixpkgs/blob/master/nixos/README-modular-services.md).

## Portable Service Options {#modular-service-options-portable}

```
id-prefix: service-opt-
list-id: service-options
source: @PORTABLE_SERVICE_OPTIONS@
```

## Systemd-specific Service Options {#modular-service-options-systemd}

```
id-prefix: systemd-service-opt-
list-id: systemd-service-options
source: @SYSTEMD_SERVICE_OPTIONS@
```

## [Installation {#ch-installation}](https://docharvest.github.io/docs/nixos/installation/installation/)

Contents

nixos

Installation {#ch-installation}

NixOS

Installation {#ch-installation}

This section describes how to obtain, install, and configure NixOS for first-time use.

```
obtaining.chapter.md
installing.chapter.md
changing-config.chapter.md
upgrading.chapter.md
building-nixos.chapter.md
building-images-via-nixos-rebuild-build-image.chapter.md
building-images-via-systemd-repart.chapter.md
```

## [NixOS Manual {#book-nixos-manual}](https://docharvest.github.io/docs/nixos/manual/)

Contents

nixos

NixOS Manual {#book-nixos-manual}

NixOS

NixOS Manual {#book-nixos-manual}

## Version @NIXOS\_VERSION@

```
preface.md
```

```
installation/installation.md
configuration/configuration.md
administration/running.md
development/development.md
```

```
contributing-to-this-manual.chapter.md
```

```
nixos-options.md
```

```
release-notes/release-notes.md
```

## [Configuration Options {#ch-options}](https://docharvest.github.io/docs/nixos/nixos-options/)

Contents

nixos

Configuration Options {#ch-options}

NixOS

Configuration Options {#ch-options}

```
id-prefix: opt-
list-id: configuration-variable-list
source: @NIXOS_OPTIONS_JSON@
```

## [Preface {#preface}](https://docharvest.github.io/docs/nixos/preface/)

Contents

nixos

Preface {#preface}

NixOS

Preface {#preface}

This manual describes how to install, use and extend NixOS, a Linux distribution based on the purely functional package management system [Nix](https://nixos.org/nix), that is composed using modules and packages defined in the [Nixpkgs](https://nixos.org/nixpkgs) project.

Additional information regarding the Nix package manager and the Nixpkgs project can be found in respectively the [Nix manual](https://nixos.org/nix/manual) and the [Nixpkgs manual](https://nixos.org/nixpkgs/manual).

If you encounter problems, please report them on the [`Discourse`](https://discourse.nixos.org), the [Matrix room](https://matrix.to/#/%23nix:nixos.org), or on the [`#nixos` channel on Libera.Chat](irc://irc.libera.chat/#nixos). Alternatively, consider [contributing to this manual](#chap-contributing). Bugs should be reported in [NixOS’ GitHub issue tracker](https://github.com/NixOS/nixpkgs/issues).

::: {.note} Commands prefixed with `#` have to be run as root, either requiring to login as root user or temporarily switching to it using `sudo` for example. :::

## [Release Notes {#ch-release-notes}](https://docharvest.github.io/docs/nixos/release-notes/release-notes/)

Contents

nixos

Release Notes {#ch-release-notes}

NixOS

Release Notes {#ch-release-notes}

This section lists the release notes for each stable version of NixOS and current unstable revision.

```
rl-2611.section.md
rl-2605.section.md
rl-2511.section.md
rl-2505.section.md
rl-2411.section.md
rl-2405.section.md
rl-2311.section.md
rl-2305.section.md
rl-2211.section.md
rl-2205.section.md
rl-2111.section.md
rl-2105.section.md
rl-2009.section.md
rl-2003.section.md
rl-1909.section.md
rl-1903.section.md
rl-1809.section.md
rl-1803.section.md
rl-1709.section.md
rl-1703.section.md
rl-1609.section.md
rl-1603.section.md
rl-1509.section.md
rl-1412.section.md
rl-1404.section.md
rl-1310.section.md
```