NixOS Wiki

FAQ/When do I update stateVersion: Difference between revisions

← Older edit
VisualWikitext
Added note to helpful tool
TLATER (talk | contribs)
7 edits
m Gives an explicit answer to the page question
 
(One intermediate revision by the same user not shown)
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>
{{Warning|<strong><code>system.stateVersion</code> should never be updated</strong>}}


The {{nixos:option|system.stateVersion}} option is described as such:
== 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>? ==


<blockquote>
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>.
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>
The consequences of changing its value range from none at all, to complete destruction of data written by specific software.


* <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>
== How do I update NixOS, if changing <code>system.stateVersion</code> does not do that? ==
* <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>
See [[Updating NixOS#Changing Nixpkgs version|Updating nixos]].


When:
== Why does <code>system.stateVersion</code> look like a NixOS version? ==
# 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]
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.
 
== 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>
Retrieved from "https://wiki.nixos.org/wiki/FAQ/When_do_I_update_stateVersion"