nixos/doc/manual/development/replace-modules.section.md

   1 # Replace Modules {#sec-replace-modules}
   2
   3 Modules that are imported can also be disabled. The option declarations,
   4 config implementation and the imports of a disabled module will be
   5 ignored, allowing another to take its place. This can be used to
   6 import a set of modules from another channel while keeping the rest of
   7 the system on a stable release.
   8
   9 `disabledModules` is a top level attribute like `imports`, `options` and
  10 `config`. It contains a list of modules that will be disabled. This can
  11 either be:
  12  - the full path to the module,
  13  - or a string with the filename relative to the modules path (eg. \<nixpkgs/nixos/modules> for nixos),
  14  - or an attribute set containing a specific `key` attribute.
  15
  16 The latter allows some modules to be disabled, despite them being distributed
  17 via attributes instead of file paths. The `key` should be globally unique, so
  18 it is recommended to include a file path in it, or rely on a framework to do it
  19 for you.
  20
  21 This example will replace the existing postgresql module with the
  22 version defined in the nixos-unstable channel while keeping the rest of
  23 the modules and packages from the original nixos channel. This only
  24 overrides the module definition, this won't use postgresql from
  25 nixos-unstable unless explicitly configured to do so.
  26
  27 ```nix
  28 { config, lib, pkgs, ... }:
  29
  30 {
  31   disabledModules = [ "services/databases/postgresql.nix" ];
  32
  33   imports =
  34     [ # Use postgresql service from nixos-unstable channel.
  35       # sudo nix-channel --add https://nixos.org/channels/nixos-unstable nixos-unstable
  36       <nixos-unstable/nixos/modules/services/databases/postgresql.nix>
  37     ];
  38
  39   services.postgresql.enable = true;
  40 }
  41 ```
  42
  43 This example shows how to define a custom module as a replacement for an
  44 existing module. Importing this module will disable the original module
  45 without having to know its implementation details.
  46
  47 ```nix
  48 { config, lib, pkgs, ... }:
  49
  50 let
  51   inherit (lib) mkIf mkOption types;
  52   cfg = config.programs.man;
  53 in
  54
  55 {
  56   disabledModules = [ "services/programs/man.nix" ];
  57
  58   options = {
  59     programs.man.enable = mkOption {
  60       type = types.bool;
  61       default = true;
  62       description = "Whether to enable manual pages.";
  63     };
  64   };
  65
  66   config = mkIf cfg.enabled {
  67     warnings = [ "disabled manpages for production deployments." ];
  68   };
  69 }
  70 ```