NixOS system configuration - Revision history

Rpqt: Add quotes to URL literals

2026-01-26T12:30:47Z

Add quotes to URL literals

← Older revision		Revision as of 12:30, 26 January 2026
Line 70:		Line 70:
	<nowiki>		<nowiki>
	{		{
	inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-unstable;		inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
	outputs = { self, nixpkgs }: {		outputs = { self, nixpkgs }: {
	# replace 'joes-desktop' with your hostname here.		# replace 'joes-desktop' with your hostname here.
Line 87:		Line 87:
	{{file\|flake.nix\|nix\|<nowiki>		{{file\|flake.nix\|nix\|<nowiki>
	{		{
	inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-unstable;		inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
	inputs.home-manager.url = github:nix-community/home-manager;		inputs.home-manager.url = "github:nix-community/home-manager";

	outputs = { self, nixpkgs, ... }@inputs: {		outputs = { self, nixpkgs, ... }@inputs: {

Asdfer: edit "more through" -> more thorough

2026-01-21T07:28:55Z

edit "more through" -> more thorough

← Older revision		Revision as of 07:28, 21 January 2026
Line 1:		Line 1:
	[[NixOS]] uses a declarative configuration system that allows users to manage their entire operating system setup including installed packages, system services, user accounts, hardware settings, and more ~~through~~ configuration files. This page serves as an overview of how to work with and manage NixOS system configurations.		[[NixOS]] uses a declarative configuration system that allows users to manage their entire operating system setup including installed packages, system services, user accounts, hardware settings, and more thorough configuration files. This page serves as an overview of how to work with and manage NixOS system configurations.

	For an introduction to declarative configuration, see the [[Overview of the NixOS Linux distribution#Declarative Configuration]] and the {{NixOS Manual\|name=NixOS official manual\|anchor=#ch-configuration}}.		For an introduction to declarative configuration, see the [[Overview of the NixOS Linux distribution#Declarative Configuration]] and the {{NixOS Manual\|name=NixOS official manual\|anchor=#ch-configuration}}.

Starfish2228: /* Importing packages from multiple nixpkgs branches */ fix overlay to respect existing config/system

2026-01-19T17:19:16Z

Importing packages from multiple nixpkgs branches: fix overlay to respect existing config/system

← Older revision		Revision as of 17:19, 19 January 2026
Line 187:		Line 187:

	inputs = {		inputs = {
	nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";		nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
	nixpkgs-unstable.url = "github:NixOS/nixpkgs/nixos-unstable";		nixpkgs-unstable.url = "github:NixOS/nixpkgs/nixos-unstable";
	};		};
Line 199:		Line 199:
	nixpkgs.overlays = [		nixpkgs.overlays = [
	(final: prev: {		(final: prev: {
	~~unstable = nixpkgs-unstable.legacyPackages.${prev.system};~~		unstable = import nixpkgs-unstable {
	~~# use this variant if unfree packages are needed:~~		inherit (final) config;
	# unstable = import nixpkgs-unstable {		inherit (final.stdenv.hostPlatform) system;
	# inherit ~~prev~~;		};
	~~# system = prev~~.system;
	~~# config.allowUnfree = true;~~
	# };
	})		})
	];		];

Volse01: minor fix of typo

2025-09-26T17:30:13Z

minor fix of typo

← Older revision		Revision as of 17:30, 26 September 2025
Line 333:		Line 333:
	* [[Updating NixOS]] - Updating the set of [[Nixpkgs]] the system uses		* [[Updating NixOS]] - Updating the set of [[Nixpkgs]] the system uses

	* [[NixOS as a ~~dekstop~~]] - Configuration tips for setting up NixOS as a desktop		* [[NixOS as a desktop]] - Configuration tips for setting up NixOS as a desktop

	* [[Nixos-rebuild]] - Command to apply changes to system configuration		* [[Nixos-rebuild]] - Command to apply changes to system configuration

Malix: /* Flake-specific tips */ update code snippets

2025-09-06T19:40:08Z

Flake-specific tips: update code snippets

← Older revision		Revision as of 19:40, 6 September 2025
Line 182:		Line 182:
	A NixOS config flake could be as follows (replace <hostname> with your hostname):		A NixOS config flake could be as follows (replace <hostname> with your hostname):

	{{file\|~~flake.nix\|nix\|~~<nowiki>		{{file\|3=<nowiki>
	{		{
	description = "NixOS configuration with two or more channels";		description = "NixOS configuration with two or more channels";
Line 214:		Line 214:
	};		};
	}		}
	</nowiki>		</nowiki>\|name=/etc/nixos/flake.nix\|lang=nix}}
	}}

	{{file\|~~flake.nix\|nix\|~~<nowiki>		{{file\|3=<nowiki>
	# can now use "pkgs.package" or "pkgs.unstable.package"		# can now use "pkgs.package" or "pkgs.unstable.package"
	{ pkgs, ... }:		{ pkgs, ... }:
Line 227:		Line 226:
	# ...		# ...
	}		}
	</nowiki>		</nowiki>\|name=/etc/nixos/configuration.nix\|lang=nix}}
	}}

	If the variable <code>nixpkgs</code> points to the flake, you can also define <code>pkgs</code> with overlays with:		If the variable <code>nixpkgs</code> points to the flake, you can also define <code>pkgs</code> with overlays with:

Iedame: /* See Also */

2025-08-10T09:19:27Z

Pigs: Create page, move some content from Flakes, NixOs as a desktop, and Overview of the NixOS Linux distributions pages to here

2025-06-08T17:58:54Z

Create page, move some content from Flakes, NixOs as a desktop, and Overview of the NixOS Linux distributions pages to here

New page

[[NixOS]] uses a declarative configuration system that allows users to manage their entire operating system setup including installed packages, system services, user accounts, hardware settings, and more through configuration files. This page serves as an overview of how to work with and manage NixOS system configurations.

For an introduction to declarative configuration, see the [[Overview of the NixOS Linux distribution#Declarative Configuration]] and the {{NixOS Manual|name=NixOS official manual|anchor=#ch-configuration}}.

== Usage ==

When you install NixOS, a default system configuration template is generated by the [[nixos-generate-config]] tool. This creates a basic <code>configuration.nix</code> file along with a corresponding <code>hardware-configuration.nix</code>, which captures detected hardware settings and filesystem definitions. After making changes to <code>configuration.nix</code>, you can apply them using [[nixos-rebuild]]:

<syntaxhighlight lang="console">
# nixos-rebuild switch
</syntaxhighlight>

Here is a simple example of a NixOS system configuration:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{ config, pkgs, ... }:

{
# Import other configuration modules
# (hardware-configuration.nix is autogenerated upon installation)
# paths in nix expressions are always relative the file which defines them
imports = [
./hardware-configuration.nix
./my-dev-tools.nix
./my-desktop-env.nix
./etc.nix
];

# Name your host machine
networking.hostName = "mymachine";

# Set your time zone.
time.timeZone = "Europe/Utrecht";

# Enter keyboard layout
services.xserver.layout = "us";
services.xserver.xkbVariant = "altgr-intl";

# Define user accounts
users.users.myuser = {
extraGroups = [ "wheel" "networkmanager" ];
isNormalUser = true;
};

# Install some packages
environment.systemPackages = with pkgs; [
ddate
testdisk
];

# Enable the OpenSSH daemon
services.openssh.enable = true;

}
</nowiki>}}

To find NixOS module options, see https://search.nixos.org/options.

== Defining NixOS as a flake ==

[[Flakes]] offer an alternative, modern way to configure NixOS systems using a standardized and reproducible structure. With flakes, the system configuration — along with any additional inputs such as Nixpkgs or external modules — is managed declaratively within a <code>flake.nix</code> file.

Unlike the traditional configuration model, which relies on <code>/etc/nixos/configuration.nix</code> and channels, flakes explicitly define their dependencies and configurations, making it easier to share, version, and reproduce complete NixOS system setups.

By default, [[Nixos-rebuild|<code>nixos-rebuild switch</code>]] will read its [[Overview_of_the_NixOS_Linux_distribution#Declarative_Configuration system configuration|configuration]] from <code>/etc/nixos/flake.nix</code> if it is present.

An example basic [[NixOS]] flake:

{{file|flake.nix|nix|
<nowiki>
{
inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-unstable;
outputs = { self, nixpkgs }: {
# replace 'joes-desktop' with your hostname here.
nixosConfigurations.joes-desktop = nixpkgs.lib.nixosSystem {
modules = [ ./configuration.nix ];
};
};
}
</nowiki>
}}

=== Accessing flake inputs ===

If you want to pass on the flake inputs to external configuration files, you can use the <code>specialArgs</code> attribute:

{{file|flake.nix|nix|<nowiki>
{
inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-unstable;
inputs.home-manager.url = github:nix-community/home-manager;

outputs = { self, nixpkgs, ... }@inputs: {
nixosConfigurations.fnord = nixpkgs.lib.nixosSystem {
specialArgs = { inherit inputs; };
modules = [ ./configuration.nix ];
};
};
}
</nowiki>
}}

Then, you can access the flake inputs from your system configuration:

{{file|configuration.nix|nix|<nowiki>
{ config, lib, inputs, ... }: {
# do something with home-manager here, for instance:
imports = [ inputs.home-manager.nixosModules.default ];
...
}
</nowiki>
}}

=== Specifying hostname ===

By default <code>nixos-rebuild</code> will use the current system hostname to look up the right NixOS configuration in <code>nixosConfigurations</code>. You can also override this by using appending it to the flake parameter:

<syntaxhighlight lang="console">
# nixos-rebuild switch --flake /etc/nixos#joes-desktop
</syntaxhighlight>

To switch a remote host you can use:

<syntaxhighlight lang="console">
$ nixos-rebuild --flake .#mymachine \
--target-host mymachine-hostname \
--build-host mymachine-hostname --fast \
switch
</syntaxhighlight>

{{note|Remote building has an issue that's [https://github.com/NixOS/nixpkgs/issues/134952#issuecomment-1367056358 resolved by setting the <code>--fast</code> flag].}}

== Tips and tricks ==

=== Using a non-default configuration location ===

By default, NixOS expects system configuration files to be located in <code>/etc/nixos/</code>, with the primary configuration file at <code>/etc/nixos/configuration.nix</code>. However, it is possible to manage your configuration from a different location.

You can specify a different configuration file when rebuilding the system by providing the path via the <code>-I</code> option:

<syntaxhighlight lang="console">
# nixos-rebuild switch -I nixos-config=/path/to/configuration.nix
</syntaxhighlight>

If you are using [[Flakes]], specify the flake path instead:

<syntaxhighlight lang="console">
# nixos-rebuild switch --flake /path/to/flake.nix
</syntaxhighlight>

To set a custom configuration location declaratively, you can configure the <code>nix.nixPath</code> option in your system configuration:

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
{
nix.nixPath = [ "path to config" ];
...
}
</nowiki>
}}

Alternatively, you may also set the location with <code>NIX_PATH="nixos-config=/path/to/configuration.nix"</code> environment variable or by symlinking <code>/etc/nixos/configuration.nix</code>.

=== Modularizing your configuration with modules ===

The <code>configuration.nix</code> file itself is an instance of a [[NixOS modules|NixOS module]], and the NixOS module system makes it straightforward to split your configuration into multiple files for better organization and reusability. Modules can:

* Import other modules
* Declare new configuration options
* Provide values for existing options (this is what most of a standard configuration.nix does)
* Reference option values from other modules (via the <code>config</code> attribute passed to all modules)

By declaring options for any values you wish to share between modules, you can structure your configuration into as many files as you like, importing them directly or indirectly from your root <code>configuration.nix</code> file. This makes it easier to manage large or complex configurations by keeping related settings together.

Additionally, you can import modules from remote sources if desired, for example using </code>builtins.fetchTarball</code> or similar functions, which is particularly useful for sharing configurations across multiple machines or pulling in reusable modules maintained elsewhere.

Refer to [[NixOS modules]] page and {{NixOS Manual|name=NixOS Manual: Chapter - Package Management|anchor=#sec-writing-modules}} for more information on modules.

=== Flake-specific tips ===

==== Importing packages from multiple nixpkgs branches ====

A NixOS config flake could be as follows (replace <hostname> with your hostname):

{{file|flake.nix|nix|<nowiki>
{
description = "NixOS configuration with two or more channels";

inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
nixpkgs-unstable.url = "github:NixOS/nixpkgs/nixos-unstable";
};

outputs =
{ nixpkgs, nixpkgs-unstable, ... }:
{
nixosConfigurations."<hostname>" = nixpkgs.lib.nixosSystem {
modules = [
{
nixpkgs.overlays = [
(final: prev: {
unstable = nixpkgs-unstable.legacyPackages.${prev.system};
# use this variant if unfree packages are needed:
# unstable = import nixpkgs-unstable {
# inherit prev;
# system = prev.system;
# config.allowUnfree = true;
# };
})
];
}
./configuration.nix
];
};
};
}
</nowiki>
}}

{{file|flake.nix|nix|<nowiki>
# can now use "pkgs.package" or "pkgs.unstable.package"
{ pkgs, ... }:
{
environment.systemPackages = [
pkgs.firefox
pkgs.unstable.chromium
];
# ...
}
</nowiki>
}}

If the variable <code>nixpkgs</code> points to the flake, you can also define <code>pkgs</code> with overlays with:

<syntaxhighlight lang="nix">
pkgs = import nixpkgs { system = "x86_64-linux"; overlays = [ /*the overlay in question*/ ]; };
</syntaxhighlight>

==== Pinning the flake registry on NixOS ====

When you use flakes, Nix resolves flake inputs using the [https://github.com/NixOS/flake-registry flake registry], a mapping of named flake URLs to specific locations (e.g. what <code>nixpkgs</code> resolves to).

By default, <code>nixpkgs</code> tracks <code>nixpkgs-unstable</code>. This can lead to silent changes in dependency resolution and increase build times as it has to fetch the latest versions.

You can lock the registry to your current system's Nixpkgs version by:

{{file|configuration.nix|nix|<nowiki>
{ inputs, ... }:
{
nix.registry = {
nixpkgs.flake = inputs.nixpkgs;
};
}
</nowiki>
}}

To make sure the registry entry is "locked" by checking against a hash, use the following:

{{file|configuration.nix|nix|<nowiki>
nix.registry = {
nixpkgs.to = {
type = "path";
path = pkgs.path;
narHash = builtins.readFile
(pkgs.runCommandLocal "get-nixpkgs-hash"
{ nativeBuildInputs = [ pkgs.nix ]; }
"nix-hash --type sha256 --sri ${pkgs.path} > $out");
};
};
</nowiki>
}}

This has the unfortunate side-effect of requiring import-from-derivation and slowing down build times, however it may greatly speed up almost every eval. Full-time flakes users may be able to just use <code>narHash = pkgs.narHash</code>.

==== Getting ''Instant'' System Flakes Repl ====

How to get a nix repl out of your system flake:

<syntaxhighlight lang="text">
$ nix repl

nix-repl> :lf /path/to/flake
Added 18 variables.

nix-repl> nixosConfigurations.myHost.config.networking.hostName
"myHost"
</syntaxhighlight>

However, this won't be instant upon evaluation if any file changes have been done since your last configuration rebuild. Instead, if one puts:

<syntaxHighlight lang=nix>
nix.nixPath = let path = toString ./.; in [ "repl=${path}/repl.nix" "nixpkgs=${inputs.nixpkgs}" ];
</syntaxHighlight>

In their system <code>flake.nix</code> configuration file, and includes the following file in their root directory flake as <code>repl.nix</code>:

<syntaxHighlight lang=nix>
let
flake = builtins.getFlake (toString ./.);
nixpkgs = import <nixpkgs> { };
in
{ inherit flake; }
// flake
// builtins
// nixpkgs
// nixpkgs.lib
// flake.nixosConfigurations
</syntaxHighlight>

(Don't forget to <code>git add repl.nix && nixos-rebuild switch --flake "/etc/nixos"</code>)
Then one can run (or bind a shell alias):

<syntaxHighlight lang=console>
$ source /etc/set-environment && nix repl $(echo $NIX_PATH | perl -pe 's|.*(/nix/store/.*-source/repl.nix).*|\1|')
</syntaxHighlight>

This will launch a repl with access to <code>nixpkgs</code>, <code>lib</code>, and the <code>flake</code> options in a split of a second.

An alternative approach to the above shell alias is omitting <code>repl</code> from <code>nix.nixPath</code> and creating a [[Shell Scripts|shell script]]:

<syntaxHighlight lang=nix>
nix.nixPath = [ "nixpkgs=${inputs.nixpkgs}" ];
environment.systemPackages = let
repl_path = toString ./.;
my-nix-fast-repl = pkgs.writeShellScriptBin "my-nix-fast-repl" ''
source /etc/set-environment
nix repl "${repl_path}/repl.nix" "$@"
'';
in [
my-nix-fast-repl
];
</syntaxHighlight>

== See Also ==

* [[Updating NixOS]] - Updating the set of [[Nixpkgs]] the system uses

* [[NixOS as a dekstop]] - Configuration tips for setting up NixOS as a desktop

* [[Nixos-rebuild]] - Command to apply changes to system configuration

* [[Home Manager]] - A system for per-user configuration environments

* [[NixOS configuration editors]] - Recommendations for improving NixOS configuration experience

* [[Configuration Collection]] - Community member's NixOS confiugration files for inspiration

[[Category:NixOS]]

← Older revision		Revision as of 09:19, 10 August 2025
Line 343:		Line 343:
	* [[NixOS configuration editors]] - Recommendations for improving NixOS configuration experience		* [[NixOS configuration editors]] - Recommendations for improving NixOS configuration experience

	* [[Configuration Collection]] - Community member's NixOS ~~confiugration~~ files for inspiration		* [[Configuration Collection]] - Community member's NixOS configuration files for inspiration

	[[Category:NixOS]]		[[Category:NixOS]]