Skip to main content
Use a maintained runtime or service version — outdated images can fail to build or carry known CVEs. See Image statuses to check your image’s status and what to do next. Once you know you need to upgrade, the steps are the same regardless of which runtime or service you use. For version-specific details, see the docs page for your runtime in Languages or your service in Add services.

​
Image statuses

“Maintained” means Active or Supported, depending on the classification below.
Some runtimes and services (for example, Redis) use the Active/Sunset/Decommissioned classification below.Others currently use the Supported/Deprecated/Retired classification, until they migrate to Active/Sunset/Decommissioned.
The Console shows an image’s status as a banner on your project’s Overview page, or as a decoration on the relevant activity in the Activity panel (active images show no decoration, since they’re always supported).An image’s status shows what’s supported and what to do:

​
Before you upgrade

Test any version change on a non-production branch before merging.

​
Upgrade a runtime

Runtimes are defined by the type key on your application in .upsun/config.yaml. Updating to a new version means changing that value and pushing it.
  1. Check your runtime’s docs page in Languages for supported versions — new versions may include breaking changes — then update the type key with the correct version number:
  1. Push to a non-production branch. If you don’t already have one, create it first:
Pushing triggers Upsun to automatically build and deploy the environment.
  1. Verify that your app builds and behaves correctly. Check the deploy log for errors:
Then open the environment and test your app manually:
  1. Merge to production:
If your project uses a source integration (GitHub, GitLab, Bitbucket), upsun merge isn’t available — merge through a pull/merge request in your Git provider instead.

​
Upgrade a service

Services are defined under the services: key in .upsun/config.yaml. Updating the type value triggers a version change on the next deploy. Whether data migrates automatically depends on the service. Check Add services before you begin.

​
In-place upgrade

Some services upgrade automatically when you change the version. PostgreSQL 10 and later, for example, include a built-in upgrade utility that runs at deploy time.
  1. Update the type key for your service:
  1. Push to a non-production branch. If you don’t already have one, create it first:
Pushing triggers Upsun to automatically build and deploy the environment.
  1. Confirm the service starts and your app connects. Check the deploy log for errors:
Then open the environment and test your app manually:
  1. Create a production backup, then merge to production:
If your project uses a source integration (GitHub, GitLab, Bitbucket), upsun merge isn’t available — merge through a pull/merge request in your Git provider instead. Downgrading is not supported after an in-place upgrade. If you need to roll back, restore from a backup.

​
Manual data migration

When a service doesn’t support in-place upgrades (for example, if you use composable image or Docker images), or when you’re moving across several major versions, you need to export your data, provision a new service at the target version, and import.
  1. Export your data from the current service.
  2. Rename the service in .upsun/config.yaml and set the target version. Renaming forces the platform to create a fresh service container.
  1. Update the relationships in any application that references the old service name:
  1. Push to a non-production branch and import your data into the new service.
  2. Verify your app works correctly, then merge to production.
Last modified on August 14, 2026