Skip to main content

Upgrading Kurtosis

The instructions in this guide assume you already have Kurtosis installed, and will walk you through upgrading to the latest version of Kurtosis.

If you're looking to install Kurtosis, see here.

I. Check breaking changes

You can check the version of the CLI you're running with kurtosis version. Before upgrading to the latest version, check the changelog to see if there are any breaking changes before proceeding with the steps below to upgrade.

II. Upgrade the CLI

brew update && brew upgrade kurtosis-tech/tap/kurtosis-cli

III. Restart the engine

If you upgraded the CLI through a minor version (the Y in a X.Y.Z version), you may need to restart your Kurtosis engine after the upgrade.

If this is needed, the Kurtosis CLI will prompt you with an error like so:

The engine server API version that the CLI expects, 1.7.4, doesn't match the running engine server API version, 1.6.8; this would cause broken functionality so you'll need to restart the engine to get the correct version by running 'kurtosis engine restart'

The fix is to restart the engine like so:

kurtosis engine restart

In order to upgrade Kurtosis to another version after you've performed a downgrade (i.e. installed a historical version), you must first uninstall the version of Kurtosis you've installed and re-install Kurtosis. When using Homebrew, the workflow will be (replacing HISTORICAL-VERSION with the historical version you have installed):

  1. brew uninstall kurtosis-tech/tap/kurtosis-cli@HISTORICAL-VERSION
  2. brew install kurtosis-tech/tap/kurtosis-cli for upgrading to the latest version or brew install kurtosis-tech/tap/kurtosis-cli@TARGET-VERSION for upgrading to a specific version
  3. kurtosis engine restart