FAQ/When do I update stateVersion: Difference between revisions
imported>Samueldr m Samueldr moved page FAQ/stateVersion to FAQ/When do I update stateVersion |
→What even is system.stateVersion for, if it is just an unchanging string?: Clarify the perceived intent of `system.stateVersion` Tags: Mobile edit Mobile web edit |
||
| (10 intermediate revisions by 6 users not shown) | |||
| Line 1: | Line 1: | ||
{{FAQ/breadcrumb | {{FAQ/breadcrumb}}<onlyinclude> | ||
<strong> | {{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>? == | |||
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>. | |||
</ | |||
The consequences of changing its value range from none at all, to complete destruction of data written by specific software. | |||
== How do I update NixOS, if changing <code>system.stateVersion</code> does not do that? == | |||
See [[Updating NixOS#Changing Nixpkgs version|Updating nixos]]. | |||
== Why does <code>system.stateVersion</code> look like a NixOS version? == | |||
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? == | |||
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. | |||
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> | ||
Latest revision as of 16:06, 5 April 2026
system.stateVersion should never be updatedWhy am I told not to update[1] system.stateVersion?
Since it is not clearly codified what system.stateVersion should be used for, and it is used for a great many different things in practice[2], there is no practical way to ensure that changing it is ever safe.
The consequences of changing its value range from none at all, to complete destruction of data written by specific software.
How do I update NixOS, if changing system.stateVersion does not do that?
See Updating nixos.
Why does system.stateVersion look like a NixOS version?
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 system.stateVersion 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 system.stateVersion 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 system.stateVersion for, if it is just an unchanging string?
Currently, this is undefined[2], 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 system.stateVersion 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.