Version Locking

What is “Locking”?

By default, the State Tool CLI is set to auto-update to the latest version. But, the State Tool CLI can be locked to a specific version by the end user to ensure that the project works as originally setup. This locking works on a per-project basis.

This effectively means the project will not be usable unless you are using a specific version of State Tool.

When should I “lock” my State Tool CLI?

There could be a lot of valid reasons to lock the State Tool CLI version, some key reasons are:

  • Ensuring project stability over time
  • Proper vetting of new releases

It’s recommended you do not use locking unless it is critically important to your workflow. Auto updating ensures you have the latest stability improvements.

How do I “lock” my State Tool CLI?

To lock your project on the current State Tool version run state update lock.

How do I “unlock” my State Tool CLI?

To unlock your project edit your activestate.yaml and remove the “lock” entry.

Alternatively if you simply want to update your lock to the latest version you can manually update it by running state update in your project directory.

How do I Install Older Versions of the State Tool?

It’s possible that you will encounter projects that have a lock whose version does not match your State Tool version. In this case you will need to either update the lock, or install the requested version of the State Tool.

To install the requested version of the State Tool use the following shell one liners, and replace the <version> with the desired State Tool Version.


For version v0.29 and beyond:

powershell -Command "& $([scriptblock]::Create((New-Object Net.WebClient).DownloadString('')))" -v <VERSION>

For version v0.28 and earlier:

powershell -Command "& $([scriptblock]::Create((New-Object Net.WebClient).DownloadString('')))" -v <VERSION>

Linux and macOS

For version v0.29 and beyond:

sh <(curl -q -v <VERSION>

For version v0.28 and earlier:

sh <(curl -q -v <VERSION>


If you encounter issues with State Tool still auto updating even though you are using locked projects you can force disable auto updates by setting the ACTIVESTATE_CLI_DISABLE_UPDATES environment variable.

Further Information