> For the complete documentation index, see [llms.txt](https://docs.zenml.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zenml.io/deploying-zenml/upgrade-zenml-server.md).

# Manage

Learn how to upgrade your server to a new version of ZenML for the different deployment options.

The way to upgrade your ZenML server depends a lot on how you deployed it. However, there are some best practices that apply in all cases. Before you upgrade, check out the [best practices for upgrading ZenML](https://docs.zenml.io/deploying-zenml/upgrade-zenml-server/best-practices-upgrading-zenml.md) guide.

{% hint style="info" %}
Check the [Compatibility](https://docs.zenml.io/changelog/compatibility) page to see which client versions work with the server version you are upgrading to.
{% endhint %}

In general, upgrade your ZenML server as soon as you can once a new version is released. New versions come with a lot of improvements and fixes from which you can benefit.

{% tabs %}
{% tab title="Docker" %}
To upgrade to a new version with docker, you have to delete the existing container and then run the new version of the `zenml-server` image.

{% hint style="danger" %}
Check that your data is persisted (either on persistent storage or on an external MySQL instance) before doing this.

Optionally also perform a backup before the upgrade.
{% endhint %}

* Delete the existing ZenML container, for example like this:

  ```bash
  # find your container ID
  docker ps
  ```

  ```bash
  # stop the container
  docker stop <CONTAINER_ID>

  # remove the container
  docker rm <CONTAINER_ID>
  ```
* Deploy the version of the `zenml-server` image that you want to use. Find all versions [here](https://hub.docker.com/r/zenmldocker/zenml-server/tags).

  ```bash
  docker run -it -d -p 8080:8080 --name <CONTAINER_NAME> zenmldocker/zenml-server:<VERSION>
  ```

{% endtab %}

{% tab title="Kubernetes with Helm" %}
To upgrade your ZenML server Helm release to a new version, follow the steps below.

#### Simple in-place upgrade

If you don't need to change any configuration values, you can perform a simple in-place upgrade that reuses your existing configuration:

```bash
helm -n <namespace> upgrade zenml-server oci://public.ecr.aws/zenml/zenml --version <VERSION> --reset-then-reuse-values
```

{% hint style="warning" %}
Use `--reset-then-reuse-values` (Helm 3.14+) rather than `--reuse-values`. With `--reuse-values`, Helm ignores the new chart version's default values and keeps the defaults of the version you originally installed, so new defaults such as the [Pod Security settings](https://docs.zenml.io/deploying-zenml/deploying-zenml/deploy-with-helm#pod-security) are never applied. In a namespace that enforces the Kubernetes Pod Security `restricted` profile, this makes the upgrade fail because the database migration pod is rejected. On older Helm versions, use the `-f custom-values.yaml` flow below instead.
{% endhint %}

#### Upgrade with configuration changes

If you need to modify your ZenML server configuration during the upgrade, follow these steps instead:

* Extract your current configuration values to a file:

  ```bash
  helm -n <namespace> get values zenml-server > custom-values.yaml
  ```
* Make the necessary changes to your `custom-values.yaml` file (make sure they are compatible with the new version)
* Upgrade the release using your modified values file:

  ```bash
  helm -n <namespace> upgrade zenml-server oci://public.ecr.aws/zenml/zenml --version <VERSION> -f custom-values.yaml
  ```

{% hint style="info" %}
It is not recommended to change the container image tag in the Helm chart to custom values, since every Helm chart\
version is tested to work only with the default image tag. However, if you know what you're doing you can change\
the `zenml.image.tag` value in your `custom-values.yaml` file to the desired ZenML version (e.g. `0.32.0`).
{% endhint %}
{% endtab %}
{% endtabs %}

## Important Considerations After Upgrading

* **Downgrading is not supported**: Downgrading the server to an older version is not supported and can lead to unexpected behavior.
* **Client-server version alignment**: Keeping the Python client on the same version as the server is the safest setup.
* **Recreate snapshots**: After upgrading your ZenML server, you need to recreate any [snapshots](https://docs.zenml.io/concepts/snapshots.md) that you were using. Snapshots are tied to specific server versions and will often not work correctly after an upgrade.

<figure><img src="https://static.scarf.sh/a.png?x-pxid=f0b4f458-0a54-4fcd-aa95-d5ee424815bc" alt="ZenML Scarf"><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zenml.io/deploying-zenml/upgrade-zenml-server.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
