> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading the Cognite Toolkit CLI and modules

> Follow these steps to upgrade the Cognite Toolkit CLI and modules to the latest version.

The Cognite Toolkit has two components: the **CLI** (command-line interface) and the **modules** (YAML configuration files stored in module folders). You must keep both components in sync to ensure compatibility.

## Prerequisites

* Python 3.10 or later installed on your machine.
* A Python package manager: `pip`, `uv`, or `poetry`.
* The Cognite Toolkit already installed. If you haven't installed it yet, see the [setup guide](/cdf/deploy/cdf_toolkit/guides/setup).

<Steps>
  <Step title="Check the current version">
    To see the currently installed version of the Cognite Toolkit CLI, run this command:

    <Tabs>
      <Tab title="pip">
        ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        pip show cognite-toolkit
        ```
      </Tab>

      <Tab title="uv">
        ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        uv pip show cognite-toolkit
        ```
      </Tab>

      <Tab title="poetry">
        ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        poetry show cognite-toolkit
        ```
      </Tab>
    </Tabs>

    Verify the installed CLI version:

    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf --version
    ```

    To check the version of the modules, open the `cdf.toml` file and look for the `[modules]` section:

    ```toml title="cdf.toml" wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    ...

    [modules]
    # This is the version of the modules. It should not be changed manually.
    # It will be updated by the 'cdf modules upgrade' command.
    version = "0.7.28"
    ...
    ```
  </Step>

  <Step title="Upgrade the Cognite Toolkit CLI">
    To upgrade the Cognite Toolkit to the **latest** version:

    <Tabs>
      <Tab title="pip">
        ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        pip install --upgrade cognite-toolkit
        ```
      </Tab>

      <Tab title="uv">
        ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        uv add cognite-toolkit --upgrade
        ```
      </Tab>

      <Tab title="poetry">
        ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        poetry add cognite-toolkit@latest
        ```
      </Tab>
    </Tabs>

    To upgrade to a **specific** version:

    <Tabs>
      <Tab title="pip">
        ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        pip install cognite-toolkit==0.7.59
        ```
      </Tab>

      <Tab title="uv">
        ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        uv add cognite-toolkit==0.7.59
        ```
      </Tab>

      <Tab title="poetry">
        ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        poetry add cognite-toolkit@0.7.59
        ```
      </Tab>
    </Tabs>

    Replace `0.7.59` with the version you want to install.
  </Step>

  <Step title="Upgrade the Cognite Toolkit modules">
    To upgrade the modules to match your installed CLI version:

    1. Run this command:

       ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
       cdf modules upgrade
       ```

    2. Follow the on-screen instructions to manually update any settings that couldn't be upgraded automatically.

    <Check>
      Run `cdf --version` and verify the output matches the version you installed. Then open `cdf.toml` and confirm the `[modules] version` has been updated.
    </Check>
  </Step>
</Steps>

## Troubleshooting

### "cdf command not found" error

A "command not found" error typically means your virtual environment is not activated. This is common when you use `uv` or `poetry` to manage Python dependencies in Visual Studio Code. If you haven't installed the Cognite Toolkit yet, see the [installation guide](/cdf/deploy/cdf_toolkit/guides/setup).

Prefix your commands with `uv run` or `poetry run` to run them in the correct virtual environment:

<Tabs>
  <Tab title="uv">
    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    uv run cdf modules upgrade
    ```
  </Tab>

  <Tab title="poetry">
    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    poetry run cdf modules upgrade
    ```
  </Tab>
</Tabs>

<Note>
  These tools don't use `pip run` because `pip` doesn't manage virtual environments. With `pip`, activate the virtual environment manually instead.
</Note>

Or activate the virtual environment manually:

<Tabs>
  <Tab title="pip">
    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    source path/to/venv/bin/activate  # Replace with your venv path
    ```
  </Tab>

  <Tab title="uv">
    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    uv activate
    ```
  </Tab>

  <Tab title="poetry">
    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    poetry shell
    ```
  </Tab>
</Tabs>

### Mismatched installed and available versions

If you install a newer version of the Cognite Toolkit CLI using `poetry` and then run `cdf --version` in the terminal, the terminal may show an older version.

```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
>> poetry add cognite_toolkit@latest
Using version ^0.7.59 for cognite-toolkit
>> cdf --version
CDF-Toolkit version: 0.6.40.
```

This happens because the terminal is not running in the same virtual environment as `poetry`. To fix this, either prefix your commands with `poetry run` or activate the virtual environment with `poetry shell`.

## Next steps

* [Using the Cognite Toolkit](/cdf/deploy/cdf_toolkit/guides/usage) -- learn how to deploy and manage resources after upgrading.
* [Release notes](/cdf/deploy/cdf_toolkit/api/toolkit_update) -- see what changed in the latest version.
* [`cdf.toml` reference](/cdf/deploy/cdf_toolkit/api/cdf_toml) -- understand the configuration file that controls module versions.