FAQ/When do I update stateVersion - Revision history

TLATER: /* What even is system.stateVersion for, if it is just an unchanging string? */Clarify the perceived intent of `system.stateVersion`

2026-04-05T16:06:00Z

What even is system.stateVersion for, if it is just an unchanging string?: Clarify the perceived intent of `system.stateVersion`

← Older revision		Revision as of 16:06, 5 April 2026
Line 29:		Line 29:
	== What even is <code>system.stateVersion</code> for, if it is just an unchanging string? ==		== What even is <code>system.stateVersion</code> for, if it is just an unchanging string? ==

	Currently, this is undefined<ref name=":1" />.		Currently, this is undefined<ref name=":1" />, though the intent is to keep track of on-disk state versions that are not supposed to change with the configuration.

	As a result, modules can effectively use it for anything, which makes the effects of changing it unpredictable.		As a result, modules can effectively use <code>system.stateVersion</code> for anything, which makes the effects of changing it unpredictable.

	Since it is sometimes used to protect data integrity upon package updates, changing the number can lead to irreversible data loss.		Since it is sometimes used to protect data integrity upon package updates, changing the number can lead to irreversible data loss.

TLATER: /* What even is system.stateVersion for, if it is just an unchanging string? */Make more explicit that people shouldn't be changing this setting, because somehow even a page full of FAQs saying you shouldn't doesn't get the point across.

2026-04-05T15:48:07Z

What even is system.stateVersion for, if it is just an unchanging string?: Make more explicit that people shouldn't be changing this setting, because somehow even a page full of FAQs saying you shouldn't doesn't get the point across.

← Older revision		Revision as of 15:48, 5 April 2026
Line 29:		Line 29:
	== What even is <code>system.stateVersion</code> for, if it is just an unchanging string? ==		== What even is <code>system.stateVersion</code> for, if it is just an unchanging string? ==

	~~Generally~~, it is ~~used to inform NixOS what versions of packages you might have previously installed. This is used to ensure correct data migration for certain packages~~<ref name=":0" />~~. Since NixOS configurations are stateless, and therefore cannot know what data may already be on your system, there is no other way to identify this~~.		Currently, this is undefined<ref name=":1" />.

	~~{{nixos:option\|system.stateVersion}} in practice is also used for other potential issues that stem from version upgrades<ref name=":1" /> -~~ it ~~is somewhat controversial what and what not it should be used~~ for, ~~resulting in many different use cases~~. ~~The current and historic lack of a clear definition of what~~ it ~~does~~ is ~~part of why it cannot be updated~~.		As a result, modules can effectively use it for anything, which makes the effects of changing it unpredictable.

			Since it is sometimes used to protect data integrity upon package updates, changing the number can lead to irreversible data loss.

	== References ==		== References ==
	</noinclude>		</noinclude>

TLATER: Gives an explicit answer to the page question

2025-08-27T15:39:36Z

Gives an explicit answer to the page question

← Older revision		Revision as of 15:39, 27 August 2025
Line 1:		Line 1:
	{{FAQ/breadcrumb}}<onlyinclude>		{{FAQ/breadcrumb}}<onlyinclude>

			{{Warning\|<strong><code>system.stateVersion</code> should never be updated</strong>}}

	== Why am I told not to update<ref name=":0">https://nixos.org/manual/nixos/stable/options#opt-system.stateVersion</ref> <code>system.stateVersion</code>? ==		== Why am I told not to update<ref name=":0">https://nixos.org/manual/nixos/stable/options#opt-system.stateVersion</ref> <code>system.stateVersion</code>? ==

TLATER: This is a complete rewrite of the page, adding more information, better references, and attempting to make it more clear that the value should never be changed; The old version was dangerously close to implying it could reasonably be changed.

2025-08-27T15:33:57Z

This is a complete rewrite of the page, adding more information, better references, and attempting to make it more clear that the value should never be changed; The old version was dangerously close to implying it could reasonably be changed.

← Older revision		Revision as of 15:33, 27 August 2025
Line 1:		Line 1:
	{{FAQ/breadcrumb}}<onlyinclude>		{{FAQ/breadcrumb}}<onlyinclude>
	~~== When do I update <code>stateVersion</code> ==~~

	~~<strong>Keep <code>stateVersion</code>~~ to ~~the version you originally installed.</strong>~~<ref>https://~~logs~~.~~nix.samueldr.com~~/nixos/~~2017~~-~~12-05#745406~~</ref>		== Why am I told not to update<ref name=":0">https://nixos.org/manual/nixos/stable/options#opt-system.stateVersion</ref> <code>system.stateVersion</code>? ==

	~~The~~ {{nixos:option\|system.stateVersion}} ~~option~~ is ~~described as such~~:		Since it is not clearly codified what {{nixos:option\|system.stateVersion}} should be used for, and it is used for a great many different things in practice<ref name=":1">https://discourse.nixos.org/t/using-hashes-for-stateversion-instead-of-human-readable-strings/61823/30</ref>, <strong>there is no practical way to ensure that changing it is ever safe</strong>.

	~~<blockquote>~~		The consequences of changing its value range from none at all, to complete destruction of data written by specific software.
	~~Every once in a while, a new NixOS release may change configuration defaults in a way incompatible with stateful data. For instance, if the default version~~ of ~~PostgreSQL changes, the new version will probably be unable to read your existing databases. To prevent such breakage~~, ~~you can set the value of this option to the NixOS release with which you want to be compatible. The effect is that NixOS will option defaults corresponding~~ to ~~the specified release (such as using an older version~~ of ~~PostgreSQL)~~.
	~~</blockquote>~~

	<~~strong~~>~~Frequent answers:~~</~~strong~~>		== How do I update NixOS, if changing <code>system.stateVersion</code> does not do that? ==

	* <code>stateVersion</code> has nothing to do with the current version ~~of the system<ref>https://logs.nix.samueldr.com/~~nixos~~/2018-04-18#1524080358-1524080429;</ref>~~		See [[Updating NixOS#Changing Nixpkgs version\|Updating nixos]].
	* <em>Do NOT</em> change the <code>stateVersion</code> in the configuration; <nowiki>[it]~~</nowiki> tells nixos what version your state is; changing it will break the things <nowiki>[it is~~]~~</nowiki> meant to fix.<ref>https://logs.nix.samueldr~~.~~com/nixos/2017-10-18#1508341107-1508341130;</ref>~~

	~~<strong>When can I update~~ <code>stateVersion</code>?~~</strong>~~		== Why does <code>system.stateVersion</code> look like a NixOS version? ==

	~~When:~~		This is because it notes down the version of NixOS you first installed with a given configuration. It does not mean that you should update it.
	~~# You have read all [https://nixos.org/manual/nixos/unstable/release-~~notes~~.html release notes] starting from your <code>stateVersion</code>.~~
	~~# You have verified all instances~~ of ~~<code>stateVersion</code> in the code in <tt><nowiki><nixpkgs/nixos></nowiki></tt>~~.
	~~# You have made all manual interventions as required by the changes previously inventoried~~.~~</onlyinclude><noinclude>~~

	~~To make sure that~~ you ~~are aware~~ of all ~~necessary changes~~ you ~~can build your configuration with the different stateversions~~ using e.g. <code>~~nixos-rebuild build~~</code> and ~~then diff~~ the system ~~derivations with [https~~:/~~/github~~.~~com~~/~~Gabriella439/nix~~-~~diff nix-diff]~~		== When can I update <code>system.stateVersion</code> safely? ==

			Currently, you cannot update it safely without a complete understanding of all NixOS modules you are using, directly or indirectly.

			Only when the NixOS release notes say that it can be changed, should it be changed.

			== Is it ok to leave <code>system.stateVersion</code> at a very old version? ==

			The NixOS module authors are aware of their use of the setting, and must ensure that old versions continue to work. Whether and how this is sustainable is an upstream issue; Users should not update the setting unless instructed otherwise.

			== What even is <code>system.stateVersion</code> for, if it is just an unchanging string? ==

			Generally, it is used to inform NixOS what versions of packages you might have previously installed. This is used to ensure correct data migration for certain packages<ref name=":0" />. Since NixOS configurations are stateless, and therefore cannot know what data may already be on your system, there is no other way to identify this.

			{{nixos:option\|system.stateVersion}} in practice is also used for other potential issues that stem from version upgrades<ref name=":1" /> - it is somewhat controversial what and what not it should be used for, resulting in many different use cases. The current and historic lack of a clear definition of what it does is part of why it cannot be updated.

	== References ==		== References ==
	</noinclude>		</noinclude>

Vherrmann: Added note to helpful tool

2025-08-03T08:05:29Z

Added note to helpful tool

← Older revision		Revision as of 08:05, 3 August 2025
Line 21:		Line 21:
	# You have verified all instances of <code>stateVersion</code> in the code in <tt><nowiki><nixpkgs/nixos></nowiki></tt>.		# You have verified all instances of <code>stateVersion</code> in the code in <tt><nowiki><nixpkgs/nixos></nowiki></tt>.
	# You have made all manual interventions as required by the changes previously inventoried.</onlyinclude><noinclude>		# You have made all manual interventions as required by the changes previously inventoried.</onlyinclude><noinclude>

			To make sure that you are aware of all necessary changes you can build your configuration with the different stateversions using e.g. <code>nixos-rebuild build</code> and then diff the system derivations with [https://github.com/Gabriella439/nix-diff nix-diff]

	== References ==		== References ==
	</noinclude>		</noinclude>

Sdht0: Fix tags

2024-05-20T22:12:23Z

Fix tags

← Older revision		Revision as of 22:12, 20 May 2024
Line 20:		Line 20:
	# You have read all [https://nixos.org/manual/nixos/unstable/release-notes.html release notes] starting from your <code>stateVersion</code>.		# You have read all [https://nixos.org/manual/nixos/unstable/release-notes.html release notes] starting from your <code>stateVersion</code>.
	# You have verified all instances of <code>stateVersion</code> in the code in <tt><nowiki><nixpkgs/nixos></nowiki></tt>.		# You have verified all instances of <code>stateVersion</code> in the code in <tt><nowiki><nixpkgs/nixos></nowiki></tt>.
	# You have made all manual interventions as required by the changes previously inventoried.<noinclude>		# You have made all manual interventions as required by the changes previously inventoried.</onlyinclude><noinclude>

	== References ==		== References ==
	</noinclude>		</noinclude>

Sdht0: /* When do I update stateVersion */ Remove blank lines

2024-05-20T22:11:55Z

When do I update stateVersion: Remove blank lines

← Older revision		Revision as of 22:11, 20 May 2024
Line 20:		Line 20:
	# You have read all [https://nixos.org/manual/nixos/unstable/release-notes.html release notes] starting from your <code>stateVersion</code>.		# You have read all [https://nixos.org/manual/nixos/unstable/release-notes.html release notes] starting from your <code>stateVersion</code>.
	# You have verified all instances of <code>stateVersion</code> in the code in <tt><nowiki><nixpkgs/nixos></nowiki></tt>.		# You have verified all instances of <code>stateVersion</code> in the code in <tt><nowiki><nixpkgs/nixos></nowiki></tt>.
	# You have made all manual interventions as required by the changes previously inventoried.		# You have made all manual interventions as required by the changes previously inventoried.<noinclude>
	~~</onlyinclude>~~<noinclude~~><hr /~~>

	== References ==		== References ==
	</noinclude>		</noinclude>

Samueldr at 05:00, 7 April 2024

2024-04-07T05:00:47Z

← Older revision		Revision as of 05:00, 7 April 2024
Line 1:		Line 1:
	{{FAQ/breadcrumb~~}}{{#tweekihide:firstHeading~~}}<onlyinclude>		{{FAQ/breadcrumb}}<onlyinclude>
	== When do I update <code>stateVersion</code> ==		== When do I update <code>stateVersion</code> ==

imported>Yuu: /* When do I update stateVersion */

2022-10-12T23:13:12Z

When do I update stateVersion

← Older revision		Revision as of 23:13, 12 October 2022
Line 18:		Line 18:

	When:		When:
	# You have read all release notes starting from your <code>stateVersion</code>.		# You have read all [https://nixos.org/manual/nixos/unstable/release-notes.html release notes] starting from your <code>stateVersion</code>.
	# You have verified all instances of <code>stateVersion</code> in the code in <tt><nowiki><nixpkgs/nixos></nowiki></tt>.		# You have verified all instances of <code>stateVersion</code> in the code in <tt><nowiki><nixpkgs/nixos></nowiki></tt>.
	# You have made all manual interventions as required by the changes previously inventoried.		# You have made all manual interventions as required by the changes previously inventoried.
	</onlyinclude><noinclude><hr />		</onlyinclude><noinclude><hr />

	== References ==		== References ==
	</noinclude>		</noinclude>

imported>Samueldr: Adds sub-section about updating it anyway.

2018-04-21T22:22:04Z

Adds sub-section about updating it anyway.

← Older revision		Revision as of 22:22, 21 April 2018
Line 14:		Line 14:
	* <code>stateVersion</code> has nothing to do with the current version of the system<ref>https://logs.nix.samueldr.com/nixos/2018-04-18#1524080358-1524080429;</ref>		* <code>stateVersion</code> has nothing to do with the current version of the system<ref>https://logs.nix.samueldr.com/nixos/2018-04-18#1524080358-1524080429;</ref>
	* <em>Do NOT</em> change the <code>stateVersion</code> in the configuration; <nowiki>[it]</nowiki> tells nixos what version your state is; changing it will break the things <nowiki>[it is]</nowiki> meant to fix.<ref>https://logs.nix.samueldr.com/nixos/2017-10-18#1508341107-1508341130;</ref>		* <em>Do NOT</em> change the <code>stateVersion</code> in the configuration; <nowiki>[it]</nowiki> tells nixos what version your state is; changing it will break the things <nowiki>[it is]</nowiki> meant to fix.<ref>https://logs.nix.samueldr.com/nixos/2017-10-18#1508341107-1508341130;</ref>

			<strong>When can I update <code>stateVersion</code>?</strong>

			When:
			# You have read all release notes starting from your <code>stateVersion</code>.
			# You have verified all instances of <code>stateVersion</code> in the code in <tt><nowiki><nixpkgs/nixos></nowiki></tt>.
			# You have made all manual interventions as required by the changes previously inventoried.
	</onlyinclude><noinclude><hr />		</onlyinclude><noinclude><hr />
	== References ==		== References ==
	</noinclude>		</noinclude>