Automatic system upgrades

Automatic system upgrades can be used to upgrade a system regularly at a specific time. This can help to reduce the time period of applying important security patches to your running software, but might also introduce some breakage in the case that an automatic upgrade fails. For automatic upgrades, automatic garbage collection is important to prevent full /boot and / partitions.

Configuration

Channel-based systems (default)

Most NixOS installations use channels by default. If you're unsure which you're using, check with nix-channel --list. If that returns any results, you're using channels.

For channel-based systems, use this configuration:

❄︎ auto-upgrade.nix

system.autoUpgrade = {
  enable = true;
  dates = "02:00";
  randomizedDelaySec = "45min";
  allowReboot = false;  # Set to true if you want automatic reboots
};

Important: Do not use flake-specific flags with channel-based systems, as they will cause the upgrade to fail silently.

Flake-based systems

To enable unattended automatic system updates on a flake-enabled host, add following to your configuration:

❄︎ auto-upgrade.nix

system.autoUpgrade = {
  enable = true;
  flake = "/path/to/flake";
  flags = [
    "--print-build-logs"
    "--commit-lock-file"  # If you want to automatically commit the updated flake.lock
  ];
  dates = "02:00";
  randomizedDelaySec = "45min";
};

Previously, this page advised to set the flags --update-input nixpkgs to trigger an update of the nixpkgs input. However, that flag will only be passed to nixos-rebuild, where it was deprecated. Follow this issue for details and resolutions.

Home Manager

To enable unattended automatic updates for Home Manager packages on a flake-enabled host, use services.home-manager.autoUpgrade option:

❄︎ ~/.config/home-manager/home.nix

services.home-manager.autoUpgrade = {
  enable = true;
  useFlake = true;
  flakeDir = "/path/to/flake";
  frequency = "03:00";
  preSwitchCommands = [ "nix flake update" ];
};

Note: The update service should be immediately triggered if it missed the last start time (for example due to the system being powered off), since Persistent is set to true both in nixos-upgrade.timer and home-manager-auto-upgrade.timer. (See https://wiki.archlinux.org/title/Systemd/Timers#Realtime_timer for more details on Persistent option.)

Monitoring

Check that automatic system upgrades run successfully. Force an automatic system upgrade by running:

# systemctl start nixos-upgrade

Check the upgrade log with:

# systemctl status nixos-upgrade.service

Or, to see the log:

# journalctl -u nixos-upgrade.service

To see the status of the upgrade timer, run:

# systemctl status nixos-upgrade.timer

Home Manager

Force upgrade by running:

# systemctl --user start home-manager-auto-upgrade.service

To see the full log:

# journalctl --user -u home-manager-auto-upgrade.service -f

To see the status of the upgrade timer, run:

# systemctl --user status home-manager-auto-upgrade.timer

Troubleshooting

Git "repository is not owned by current user"

The flake repository directory is not owned by root, which nixos-upgrade runs as. To fix this, add the following to /root/.gitconfig:

≡︎ /root/.gitconfig

[safe]
  directory = /path/to/flake

Git "fatal: unable to auto-detect email address"

The root user doesn't have specified the user and email in the git configuration. To fix this, you can extend the nixos-upgrade service with:

❄︎ auto-upgrade.nix

systemd.services.nixos-upgrade.environment = {
  GIT_AUTHOR_NAME = "NixOS Auto-upgrade";
  GIT_AUTHOR_EMAIL = "root@{your hostname}";
  GIT_COMMITTER_NAME = "NixOS Auto-upgrade";
  GIT_COMMITTER_EMAIL = "root@{your hostname}";
};