FAQ/When do I update stateVersion: Difference between revisions

(2 intermediate revisions by the same user not shown)

Line 1:

{{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>? ==

Line 27:

Line 29:

== 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" />, 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 <code>system.stateVersion</code> for anything, which makes the effects of changing it unpredictable.

~~{{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~~.

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

== References ==

</noinclude>

@@ Line 1: / Line 1: @@
 {{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>? ==
@@ Line 27: / Line 29: @@
 == 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" />, 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 <code>system.stateVersion</code> for anything, which makes the effects of changing it unpredictable.
-{{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.
+Since it is sometimes used to protect data integrity upon package updates, changing the number can lead to irreversible data loss.
 == References ==
 </noinclude>