nixos-option

List all subkeys of a given option key

$ nixos-option [option_key]

$ nixos-option boot.kernelModules

$ nixos-option users.users.[username].openssh.authorizedKeys.[keyFiles|keys]

$ nixos-option nix.buildMachines

$ NIXOS_CONFIG=[path_to_configuration.nix] nixos-option [option_key]

$ nixos-option [[-r|--recursive]] users.users.[user]

nixos-option [OPTIONS] [NAME...]

-h, --help
    Displays the help message and exits.

--json
    Outputs the option information in JSON format, suitable for programmatic parsing.

--xml
    Outputs the option information in XML format.

--builtins
    Includes options that are built into Nix itself, beyond just NixOS specific modules.

--type
    Shows the expected type of the option (e.g., string, boolean, listOf package).

--value
    Shows the current evaluated value of the option based on the configuration.

--file
    Specifies a path to a NixOS configuration file to query options from, instead of the active system.

--flake
    Specifies a Nix flake reference (e.g., .#nixosConfigurations.my-system) to evaluate options from.

--system
    Specifies the system architecture (e.g., x86_64-linux) for evaluation.

--system-path
    Specifies the path to an existing system closure, overriding the system detected or specified by --system.

--root
    Specifies the path to the NixOS installation directory.

--cores
    Sets the number of CPU cores to use for Nix evaluation.

--max-memory-size
    Sets the maximum memory size in MB to be used by Nix for evaluation.

--option
    Passes a specific Nix option (e.g., binary-caches) with a custom value to the evaluation context.

--show-trace
    Displays detailed Nix evaluation traces on errors, useful for debugging.

--override-input
    Overrides a specific flake input with a custom path during evaluation.

--rebuild-d-dir
    Specifies a directory for rebuild-d files (internal use for development).

--tarball-url
    Specifies a URL to fetch the nixpkgs tarball from, for non-flake configurations.

--impure
    Allows impure evaluation, which can access files outside the Nix store (e.g., /dev/urandom).

nixos-option is a powerful command-line utility for exploring and querying the vast array of configuration options available within a NixOS system. It allows users to search for, view the type of, and retrieve the current evaluated value of specific NixOS options. This tool is indispensable for NixOS administrators and developers, enabling them to efficiently navigate the extensive configuration space, understand available settings, and diagnose system configuration issues.

It can query options from the currently running system, a specified NixOS configuration file, or even a Nix flake, providing flexibility for various development and debugging scenarios. By understanding the options and their current values, users can more effectively write and debug their declarative NixOS configurations.

nixos-option evaluates the NixOS configuration to provide accurate information, which can be computationally intensive and time-consuming for large or complex systems. It requires a NixOS environment or a specified configuration/flake to function correctly. Using the --value option might trigger extensive evaluation, potentially leading to long execution times or errors if the configuration is broken or contains undeclared dependencies.

Users can execute nixos-option without any arguments to list all available top-level configuration options. To narrow down the search, a partial name can be provided, such as nixos-option networking, which will display all options related to networking. This interactive exploration greatly aids in finding relevant configuration points.

By combining options like --type and --value, users can inspect both the expected type and the currently evaluated value of a specific option within their configuration. For example, nixos-option boot.loader.systemd-boot.enable --type --value provides crucial insights for debugging configuration discrepancies or unexpected system behavior.

The --json output format makes nixos-option an excellent candidate for scripting and integration into other tools or automated workflows. This allows developers to build custom scripts that dynamically query and respond to NixOS configuration details.

The nixos-option command emerged as a vital tool with the growth and increasing complexity of the NixOS declarative configuration system. As NixOS evolved, defining system state through a vast module system and numerous configuration options, the need for a straightforward way to discover and inspect these options directly from the command line became paramount. It significantly simplified the process for users and developers to understand and interact with the intricate NixOS configuration space, moving beyond simply relying on external documentation or manual exploration of source code.

nixos-rebuild(8), nix(1), nix search(1), nix-instantiate(1), man configuration.nix(5)