Skip to main content
Version: 0.68.12

Installing, Upgrading & Configuring The CLI

The instructions in this guide will walk you through installing, upgrading, & configuring the CLI.


Kurtosis supports tab completion, and we strongly recommend installing it after you finish installing the CLI.

Installing the CLI

There are a few ways to install the CLI and the below section will guide you through each of those ways. Once you're done installing the CLI, the quickstart is a great place to get started.

MacOS (Homebrew)

To install on MacOS (Homebrew):

brew install kurtosis-tech/tap/kurtosis-cli

NOTE: Homebrew might warn you that your Xcode is outdated or missing entirely. This is a Homebrew requirement, and has nothing to do with Kurtosis (which ships as prebuilt binaries). To install or update your Xcode, run:

xcode-select --install

To install on Ubuntu OS using apt:

echo "deb [trusted=yes] /" | sudo tee /etc/apt/sources.list.d/kurtosis.list
sudo apt update
sudo apt install kurtosis-cli

To install on RPM-based Linux systems:

echo '[kurtosis]
gpgcheck=0' | sudo tee /etc/yum.repos.d/kurtosis.repo
sudo yum install kurtosis-cli
deb, rpm, and apk

Download the appropriate artifact from the release artifacts page.


The Kurtosis CLI cannot be installed directly on Windows. Windows users are encouraged to use Windows Subsystem for Linux (WSL) to use Kurtosis.

Upgrading the CLI

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


if you're upgrading the CLI's 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

To upgrade the CLI on MacOS (Homebrew):

brew upgrade kurtosis-tech/tap/kurtosis-cli

If you encounter issues with upgrading the CLI using Homebrew, try the following command to update and upgrade Homebrew itself before upgrading the CLI:

brew update && brew upgrade

To upgrade the CLI on Ubuntu OS using apt:

apt install --only-upgrade kurtosis-cli

To upgrade the CLI on RPM-based Linux systems:

yum upgrade kurtosis-cli
deb, rpm, and apk

Download the appropriate artifact from the release artifacts page.

Configuring Analytics

On installation, Kurtosis enables anonymized analytics by default. In case you want to disable it, you can run: kurtosis analytics disable to disable the sending of product analytics metrics.

Read more about why and how we collect product analytics metrics here.