> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-self-hosted/operations/upgrades/updates.md).

# Update to a new version

Updating your CARTO Self-Hosted deployment

## Support lifecycle policy

At CARTO, we are committed to providing reliable, secure, and high-quality support for all our users. To ensure the best experience, our support services are available **only for CARTO Self-hosted versions released within the past 12 months**.

Maintaining your installation on an up-to-date version is essential to:

* Guarantee **optimal performance** of the platform.
* Ensure **security and compliance** through the latest patches.
* Benefit from **continuous improvements**, including new features and resolved issues.

{% hint style="danger" %}
We strongly recommend that all users ***regularly update their CARTO installations***. Doing so not only secures continued eligibility for support services but also allows you to take full advantage of CARTO's latest capabilities and innovations.
{% endhint %}

Keeping your environment current is the best way to maximize the value of your CARTO deployment while ensuring stability, security, and a seamless user experience.

## Upgrade Selfhosted version

Follow the steps below if you're using an Orchestrated container deployment in Kubernetes.

{% hint style="danger" %}
**Warning: Version rollbacks are not supported**

CARTO Self-Hosted does **not support** rolling back to previous versions. This includes:

* Using `helm rollback` to revert to an older release
* Installing a previous chart version after upgrading
* Downgrading the `appVersion` in any way

**Why?** Database schema migrations run automatically during upgrades and are designed to be forward-only. Rolling back the application while the database remains at a newer schema version will cause:

* Application errors due to schema mismatches
* Potential data corruption
* Features becoming non-functional
  {% endhint %}

{% hint style="danger" %}
**If an upgrade fails:** Contact CARTO Support immediately. Do not attempt to rollback. If you must restore to a previous state, you will need to restore from a database backup taken **before** the upgrade and reinstall the matching chart version.
{% endhint %}

## Pre-upgrade requirements

{% hint style="info" %}
Important: **Always Back Up Your Databases Before Upgrading**
{% endhint %}

Before performing any upgrade to a new CARTO Self-Hosted version, you **must** create a backup of your databases:

1. **Backup the following databases:**
   * `carto` / `metadata` - Main CARTO metadata database (PostgreSQL) - **Required**
   * `aiproxy` - AI Proxy database (PostgreSQL) - ***Only if AI features are enabled***
2. **Verify backups are complete and restorable** before proceeding with the upgrade.
3. **Document the current chart version** (`helm list -n <namespace>`) in case you need to reinstall.

This is your only recovery path if an upgrade fails. Without a pre-upgrade backup, rolling back to a previous working state is not possible.

## Download customer package (Helm)

{% hint style="info" %}
This section only applies to **advanced Orchestrated container deployments** using **Kubernetes** and **Helm**.
{% endhint %}

Once a new release is available, you will need to download the latest customer package.

Clone the CARTO Self-Hosted github repo:

```
git clone https://github.com/CartoDB/carto-selfhosted.git
cd carto-selfhosted
```

Checkout to the [latest stable release](https://github.com/CartoDB/carto-selfhosted/releases):

```
git checkout tags/2026.9.4
```

You should Install the following packages on your machine:`yq`, `jq` and `gcloud`.

Run the script passing the following arguments:

<table><thead><tr><th width="132.5" align="center">flag</th><th>description</th></tr></thead><tbody><tr><td align="center"><code>-d</code></td><td>Directory containing the existing customer package files.</td></tr><tr><td align="center"><code>-s</code></td><td>Carto selfhosted installation mode. Possible values for mode are <code>docker</code> (Single VM deployment) and <code>k8s</code>(Orchestrated container deployment)</td></tr></tbody></table>

<pre class="language-bash" data-full-width="false"><code class="lang-bash"><strong>./tools/carto-download-customer-package.sh -s k8s -d /tmp/carto
</strong></code></pre>

Example output:

```bash
ℹ️  selfhosted mode: k8s
✅ found: ../carto3-onprem-customers/package/<customer-id>/k8s/carto-values.yaml
✅ found: ../carto3-onprem-customers/package/<customer-id>/k8s/carto-secrets.yaml
✅ activating: service account credentials for: [xxx@xxx.iam.gserviceaccount.com]
ℹ️  latest version: 2025-1-10
ℹ️  download file: gs://xxx-customer-package-storage/customer-package/carto-selfhosted-k8s-customer-package-<customer-id>-2025-1-10.zip
Copying gs://xxx-customer-package-storage/customer-package/carto-selfhosted-k8s-customer-package-<customer-id>-2025-1-10.zip...
/ [1 files][  3.0 KiB/  3.0 KiB]
Operation completed over 1 objects/3.0 KiB.
✅ downloading: carto-selfhosted-k8s-customer-package-<customer-id>-2025-1-10.zip

##############################################################
Current selfhosted version in [carto-values.yaml]: 2024-12-10
Latest selfhosted version downloaded: 2025-1-10
Downloaded file: carto-selfhosted-k8s-customer-package-<customer-id>-2025-1-10.zip
Downloaded from: gs://xxx-customer-package-storage/customer-package/carto-selfhosted-k8s-customer-package-<customer-id>-2025-1-10.zip
##############################################################

✅ finished [0]
```

## Install upgrade

{% tabs %}
{% tab title="Kots" %} <img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-9eca52f0d85c9aacba5a62150e03b4faee188bd8%2Ftool-kots.svg?alt=media" alt="Kots" width="18">

### Upgrade Single VM deployment

To upgrade your CARTO Self-Hosted deployment, simply access the Admin Console and check for any available updates.

{% hint style="warning" %}
**cgroup v2 required:** Since embedded-cluster `2.18.1+k8s-1.35`, the embedded Kubernetes distribution (k0s) requires the host to boot with cgroup v2 and will fail to start on cgroup v1 hosts. Some distributions (for example RHEL/CentOS 8.x) still default to cgroup v1. Before upgrading, verify your host with `stat -fc %T /sys/fs/cgroup/` (expected output: `cgroup2fs`). See [Hardware & Software Requirements](/carto-self-hosted/planning/prerequisites/hardware-requirements.md) for migration steps if you're still on cgroup v1.
{% endhint %}

1. Login to the **Admin Console**.
2. Click on "**Check for Updates**" link.
3. If there are [new SelfHosted version availabile](/carto-self-hosted/release-notes.md), you will see it in the "New version available" section in the **Admin Console**.
4. Wait for the **Preflight Checks** to *Complete*.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-3eb85795f1bae5ccfac8eaaf9e6515b3b99eb395%2FScreenshot%202024-03-14%20at%2012.32.53.png?alt=media" alt=""><figcaption></figcaption></figure>

5. Click on the blue **"Deploy"** button to deploy your new version.
6. Monitor the progres in the **"Details"** section.

{% hint style="info" %}
Once the update has been downloaded and all the preflight checks have completed successfully, initiate the upgrade process by clicking the "Deploy" button. Upon completion of the deployment, your single VM deployment will be successfully updated to the latest version.
{% endhint %}

{% hint style="info" %}
The version shown in the Admin Console is the **KOTS / Helm chart version**, not the CARTO Self-Hosted release version. Check the [Release Notes](/carto-self-hosted/release-notes.md), where each entry lists its corresponding *KOTS / Helm chart version*.
{% endhint %}

### Upgrade Orchestrated container deployment (Kots in K8s)

Follow the steps below if you're using an Orchestrated container deployment in Kubernetes.

1. Login to the **Admin Console**.
2. Click on "**Check for Updates**" link.
3. If there are [new SelfHosted version availabile](/carto-self-hosted/release-notes.md), you will see it in the "New version available" section in the **Admin Console**.
4. Wait for the **Preflight Checks** to *Complete*.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-3eb85795f1bae5ccfac8eaaf9e6515b3b99eb395%2FScreenshot%202024-03-14%20at%2012.32.53.png?alt=media" alt=""><figcaption></figcaption></figure>

5. Click on the blue **"Deploy"** button to deploy your new version.
6. Monitor the progres in the **"Details"** section.

{% hint style="info" %}
Once the update has been downloaded and all the preflight checks have completed successfully, initiate the upgrade process by clicking the "Deploy" button. Upon completion of the deployment, your CARTO Deployment i K8s with Kots will be successfully updated to the latest version.
{% endhint %}

{% hint style="info" %}
The version shown in the Admin Console is the **KOTS / Helm chart version**, not the CARTO Self-Hosted release version. Check the [Release Notes](/carto-self-hosted/release-notes.md), where each entry lists its corresponding *KOTS / Helm chart version*.
{% endhint %}

### Upgrade the KOTS Admin Console (when required)

The **KOTS Admin Console** (`kotsadm`) is Replicated's management tool, and it is versioned independently of CARTO Self-Hosted. Because of this, **most CARTO upgrades do not require you to change it**. Upgrade the Admin Console only when one of the following applies:

* **The Admin Console requires it during an upgrade**: CARTO defines a minimum supported KOTS version (`minKotsVersion`). If your Admin Console is below it, the upgrade is blocked until you upgrade KOTS. You can check the current minimum in [`kots-app.yaml`](https://github.com/CartoDB/carto-selfhosted-helm/blob/main/manifests/kots-app.yaml).
* **A release note explicitly calls it out**: Only some releases raise the minimum KOTS version. When one does, that release's notes will mention it. If a release note does not mention KOTS, no KOTS upgrade is required for it.

Always upgrade the Admin Console **independently of the CARTO upgrade** to avoid conflicts or delays.

**Steps to upgrade KOTS:**

1. On your local machine, install the latest KOTS CLI (it is always at or above CARTO's minimum supported version). To pin a specific version instead, replace `install` with `install/vX.Y.Z`:

```
curl https://kots.io/install | bash
```

2. Upgrade the Admin Console in the cluster:

```
kubectl kots admin-console upgrade -n <namespace>
```

{% endtab %}

{% tab title="Helm" %} <img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-ba881227fa0a4e04d6d1ddbe193d0e0de6876521%2Ftool-helm.svg?alt=media" alt="Helm" width="18">

### Run Helm upgrade

1\) Update the helm chart:

```
helm repo update
```

2\) Download the latest customer package (using the repo downloaded in the previous step)

`./tools/carto-download-customer-package.sh -d . -s k8s`

3\) Upgrade the CARTO application

```
helm upgrade \
  carto \
  carto/carto \
  -f carto-values.yaml \
  -f carto-secrets.yaml \
  -f customizations.yaml
```

{% endtab %}
{% endtabs %}

## Post-change verification

After applying an update, confirm the deployment is healthy:

* [ ] All pods are in `Running` or `Completed` state
* [ ] The CARTO application is reachable and you can log in
* [ ] The Admin Console shows the expected new version
* [ ] A basic map renders successfully
* [ ] Data warehouse connections are healthy


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.carto.com/carto-self-hosted/operations/upgrades/updates.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.