# Option Declarations {#sec-option-declarations}

An option declaration specifies the name, type and description of a
NixOS configuration option. It is invalid to define an option that
hasn't been declared in any module. An option declaration generally
looks like this:

```nix
{
  options = {
    name = mkOption {
      type = type specification;
      default = default value;
      example = example value;
      description = "Description for use in the NixOS manual.";
    };
  };
}
```

The attribute names within the `name` attribute path must be camel
cased in general but should, as an exception, match the [ package
attribute name](https://nixos.org/nixpkgs/manual/#sec-package-naming)
when referencing a Nixpkgs package. For example, the option
`services.nix-serve.bindAddress` references the `nix-serve` Nixpkgs
package.

The function `mkOption` accepts the following arguments.

`type`

:   The type of the option (see [](#sec-option-types)). This
    argument is mandatory for nixpkgs modules. Setting this is highly
    recommended for the sake of documentation and type checking. In case it is
    not set, a fallback type with unspecified behavior is used.

`default`

:   The default value used if no value is defined by any module. A
    default is not required; but if a default is not given, then users
    of the module will have to define the value of the option, otherwise
    an error will be thrown.

`defaultText`

:   A textual representation of the default value to be rendered verbatim in
    the manual. Useful if the default value is a complex expression or depends
    on other values or packages.
    Use `lib.literalExpression` for a Nix expression, `lib.literalMD` for
    a plain English description in [Nixpkgs-flavored Markdown](
    https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format.

`example`

:   An example value that will be shown in the NixOS manual.
    You can use `lib.literalExpression` and `lib.literalMD` in the same way
    as in `defaultText`.

`description`

:   A textual description of the option in [Nixpkgs-flavored Markdown](
    https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format that will be
    included in the NixOS manual.

## Utility functions for common option patterns {#sec-option-declarations-util}

### `mkEnableOption` {#sec-option-declarations-util-mkEnableOption}

Creates an Option attribute set for a boolean value option i.e an
option to be toggled on or off.

This function takes a single string argument, the name of the thing to be toggled.

The option's description is "Whether to enable \<name\>.".

For example:

::: {#ex-options-declarations-util-mkEnableOption-magic .example}
### `mkEnableOption` usage
```nix
lib.mkEnableOption "magic"
# is like
lib.mkOption {
  type = lib.types.bool;
  default = false;
  example = true;
  description = "Whether to enable magic.";
}
```
:::

### `mkPackageOption` {#sec-option-declarations-util-mkPackageOption}

Usage:

```nix
mkPackageOption pkgs "name" { default = [ "path" "in" "pkgs" ]; example = "literal example"; }
```

Creates an Option attribute set for an option that specifies the package a module should use for some purpose.

**Note**: You should make package options for your modules, where applicable. While one can always overwrite a specific package throughout nixpkgs by using [nixpkgs overlays](https://nixos.org/manual/nixpkgs/stable/#chap-overlays), they slow down nixpkgs evaluation significantly and are harder to debug when issues arise.

The package is specified in the third argument under `default` as a list of strings
representing its attribute path in nixpkgs (or another package set).
Because of this, you need to pass nixpkgs itself (or a subset) as the first argument.

The second argument may be either a string or a list of strings.
It provides the display name of the package in the description of the generated option
(using only the last element if the passed value is a list)
and serves as the fallback value for the `default` argument.