---
title: "Update the image of an instance"
description: "Swap a TIR Instance's image for another pre-built, Base OS, or custom image on the same instance, keeping its workspace and plan."
content_type: "how-to"
product: "tir-instance"
platform: "TIR"
url: "/tir/tir-instance/how-to/update-the-image-of-an-instance/"
topic: ["power-and-lifecycle"]
---

# Update the image of an instance

Update the image of an instance to move it to another framework, a newer version of its image, or
your own custom image, and keep the same instance. Its workspace at `/home/jovyan`, its plan, its
workspace size, and its other settings stay as they are. Only the image and its app change.

## Before you begin

- An instance in any status except **Saving Image** or **Expired**. You can update it while it
  runs.
- Permission to update instances in the project. Every project role except **MEMBER** has it, and a
  **MEMBER** needs a policy that allows updates.
- SSH turned on for the instance, if the new image has no app. A Base OS image, a public image, and
  a custom image without **JupyterLab Support** are reached over SSH only. SSH needs at least one
  SSH key and a security group that allows port 22. See [Connect to an instance over
  SSH](/tir/tir-instance/how-to/connect-to-an-instance-over-ssh/).
- For a custom image: the image in a registry namespace of the project's **Container Registry**, in
  the same region. See [Create an instance from your own
  image](/tir/tir-instance/how-to/create-an-instance-from-your-own-image/).

Updating the image of a running instance restarts it and stops every running process. Files in
`/home/jovyan`, on mounted datasets and file systems, and in `/mnt/local` are kept, so save your
work there first. To keep the packages you installed on the current image, [save the instance as an
image](/tir/tir-instance/how-to/save-an-instance-as-an-image/) before you update it.

## Choose the new image

1. In the instance's actions menu, select **Update Image**. The image the instance uses now is
   under **Current Image Details**.
2. Choose the new image on one of the tabs:
   - **TIR Pre-built**: images that E2E maintains, each with a framework and an app such as
     JupyterLab.
   - **Base OS**: operating-system images with no app, reached over SSH.
   - **Custom Images**: an image from your project's Container Registry, or a public image that you
     name with its tag. TIR checks a public image when you submit it, and refuses one that fails the
     check.
3. Select **Update Image**.
4. Select **Update** to confirm.

## What happens after the update

On a running instance, the update restarts the instance with the new image, and it is back to
**Running** once the new container starts. Open the app with **Launch App**, or connect over
SSH, to work with the new image.

A stopped instance stays stopped, and uses the new image the next time you start it.

After the update:

- Files in `/home/jovyan`, on mounted datasets and file systems, and in `/mnt/local` are kept.
- Files elsewhere in the container and packages you installed yourself are gone.
- Programs you were running have stopped. Start them again, or let a [start
  script](/tir/tir-instance/how-to/run-start-scripts-on-an-instance/) start them each time the
  instance starts.
- The plan, the workspace size, and the instance's other settings stay as they were.

To go back to an image you saved from this instance, use **Restore Image** on its **Images** tab. A
restore works like an image update and keeps the workspace. See [Save an instance as an
image](/tir/tir-instance/how-to/save-an-instance-as-an-image/).

To give the instance a different amount of CPU, GPU, or memory, see [Change the plan of an
instance](/tir/tir-instance/how-to/change-the-plan-of-an-instance/). If it stays on **Waiting**
after the update, for example because TIR fails to download a custom image from its registry, see
[Troubleshooting TIR Instances](/tir/tir-instance/troubleshooting/tir-instance/).