--- title: "Save an instance as an image" description: "Save a running TIR Instance as a Docker image in your Container Registry, then launch, restore, or pull it, and delete it when done." content_type: "how-to" product: "tir-instance" platform: "TIR" url: "/tir/tir-instance/how-to/save-an-instance-as-an-image/" topic: ["power-and-lifecycle"] --- # Save an instance as an image **Save Image** saves a running instance's container as a Docker image in a Container Registry namespace of your project, with the packages you installed. Launch new instances from it, put it back on this instance after a restart or a plan change, or pull it with Docker. Save an image before a change you would want to undo, such as an image update, a plan change, or a framework upgrade. An image also gives your project one environment that everyone launches from. TIR saves the image while the instance keeps running. ## What the image keeps | In the saved image | Left out of the saved image | | --------------------------------------------------- | ----------------------------------------------------------------------- | | Files outside the workspace | The workspace at `/home/jovyan`: your files, notebooks, and checkpoints | | Packages installed with `apt` | Packages installed with `pip install --user` | | Packages installed with a system-wide `pip install` | Packages in a virtual environment under `/home/jovyan` | | Edits to `/root/.bashrc` | Data on mounted datasets, SFS, and PFS | To carry a package in a saved image, install it with `apt` or with a system-wide `pip install`. A new instance launched from the saved image starts with an empty workspace. Restoring the image on this instance instead keeps its workspace as it is. For what each part of an instance keeps, see [Where your files live on an instance](/tir/tir-instance/concepts/where-your-files-live/). ## Before you begin - An instance that is **Running**. **Save Image** is available only in that status. - A registry namespace in the project's **Container Registry**, in the side menu under **Storage**. If you need one, a link in the save form creates it right from the form. The link shows when you have permission to create a Container Registry. - Permission to update instances in the project. Every project role except **MEMBER** has it, and a **MEMBER** needs a policy that allows updates. The saved image is billed as Container Registry storage for as long as it stays in the registry, even after you stop or delete the instance. A namespace is charged for its peak size in each calendar month, and deleting the image ends its charge. See [pricing](https://www.e2enetworks.com/pricing). ## Save the image The saved image leaves out the workspace at `/home/jovyan`. Before you save, copy any files and checkpoints you need to mounted storage or to your own machine. See [Copy files to and from an instance](/tir/tir-instance/how-to/copy-files-to-and-from-an-instance/) and [Mount datasets and file systems on an instance](/tir/tir-instance/how-to/mount-datasets-and-file-systems/). 1. In the instance's actions menu, or on its **Images** tab, select **Save Image**. 2. In **Image Name**, enter a name, such as `pytorch-env-v1`. Use lowercase letters and digits, and separate parts with dots, underscores, or hyphens, up to two of these characters in a row. The name starts and ends with a letter or digit and is three to 120 characters long. 3. (Optional) In **Image Tag (Optional)**, enter a version label, such as `v1.0`. A tag uses letters, digits, dots, underscores, and hyphens, and starts with a letter, a digit, or an underscore. Left blank, the tag is `latest`. 4. In **Container Registry**, choose the namespace to save the image in, and select **Create**. 5. Select **Save**. TIR builds the image and pushes it to your registry, where its storage charges apply. Until then, the instance's app and actions are on hold. ## While the image is saving The instance is **Saving Image** while TIR builds the image. Once the save finishes, you can open the app again and stop, restart, update, or delete the instance. One instance runs one save at a time, and a namespace builds one image with the same name and tag at a time. When the build finishes, the instance shows **Running** again on its own. TIR emails the person who started the save when it succeeds or fails, with the team owner and admins in copy. ## Find the saved image Every image saved from the instance is on its **Images** tab. While TIR works, the image goes from **Building** to **Pushing**, and it ends as **Succeeded** or **Failed**. **Not Found** means the image has been removed from the registry. You also find the image in **Container Registry**, on the **Images** tab of the namespace you chose. ## Use the saved image An image is ready to use once its status is **Succeeded**. ### Launch a new instance from the image Select **Create Instance**, choose the **Custom Images** tab, set **Image Type** to **Private**, pick the **Registry Namespace**, and select the image under **Available Images**. Complete the form as described in [Create an instance from your own image](/tir/tir-instance/how-to/create-an-instance-from-your-own-image/). To copy another instance's settings as well, pick the saved image in the clone form. See [Clone an instance](/tir/tir-instance/how-to/clone-an-instance/). ### Restore the image on this instance On the instance's **Images** tab, select **Restore Image** on the image. The instance restarts with the saved image and keeps its workspace at `/home/jovyan`. If the image has been removed from the registry, the restore is refused and its status changes to **Not Found**. ### Pull the image with Docker To use the image outside TIR, log in with the namespace's own registry username and password, which are separate from your TIR sign-in, then pull it. Find them under **Container Registry**, in the side menu under **Storage**. The namespace's row has its **Username**, and its terminal button under **Commands** gives a ready **Docker Login Command**. If Docker refuses the login, copy the command again from there. Replace `` with the namespace's registry username, `` with the registry namespace, `` with the image name, and `` with its tag. For an image saved in Delhi: ```bash docker login registry.e2enetworks.net -u docker pull registry.e2enetworks.net//: ``` For an image saved in Chennai: ```bash docker login in-south1-registry.e2enetworks.net -u docker pull in-south1-registry.e2enetworks.net//: ``` Docker asks for your Container Registry password after the login command. For example, to pull the image `pytorch-env-v1` with the tag `latest` from the namespace `my-project-images` in Delhi: ```bash docker pull registry.e2enetworks.net/my-project-images/pytorch-env-v1:latest ``` ## Name and test your images Give each image a name and a version tag that say what it is, such as `pytorch-finetune` tagged `v2`, rather than reusing `latest` every time. You can then tell versions apart and launch the one you want. Launch an instance from a new image and check that it behaves as expected before you rely on it elsewhere. ## Delete a saved image Delete an image once you are done with it, so you stop paying for it in the registry. Deleting a saved image also removes it from the registry, and the deletion is permanent. 1. On the instance's **Images** tab, select **Delete Image** on the image. It is available once the image is past **Building** and **Pushing**. You need permission to delete images in Container Registry. 2. Confirm the deletion. TIR keeps an image that a resource is still using and refuses to delete it. Deleting the instance itself leaves its saved images in the Container Registry, still billed until you delete them. If the instance stays on **Saving Image**, or an instance launched from the image does not start, see [Troubleshooting TIR Instances](/tir/tir-instance/troubleshooting/tir-instance/).