# Docker Images: Pull, Build, Run, and Clean Up Images
URL: https://ctrlops.io/docs/modules/docker/images
Published: 2026-11-05
Updated: 2026-11-11

The Images tab lists every Docker image on your server, with its size and the containers that use it. Pull an image from a registry, build one from your code, run a container from it, and remove the ones you no longer need.

The **Images** tab shows every image on this server. From here you can get a new image, start a container from one, build your own, and clear out old ones.

> **New to Docker?**
> 
> An *image* is the template a container starts from, and one image can start many containers. A *tag* names a version of an image, such as `nginx:1.27`. A *registry*, such as Docker Hub, is where images are stored.

![The Docker Images tab showing 3 images using 1.6 GB, the All, In use, Unused, and Untagged filters, the Search images box and the Remove unused, Create Image, and Pull Image buttons, and the mysql, kornkitti/express-hello-world, and ubuntu images, each used by 1 container, with a Run button and a bin icon](https://cdn.ctrlops.io/docs/docker-images-list.webp)

The In use column shows how many containers need each image.

[Watch: Manage Docker Images Visually - See What's In Use & Safe to Delete (CtrlOps)](https://www.youtube.com/watch?v=6dJNFqBcDAY)

## Find what you need

| I want to | Instead of typing | Go to |
| --- | --- | --- |
| See my images and their size | `docker images` | [Read the list](#read-the-image-list) |
| See what is inside an image | `docker image inspect`, `docker history` | [See the details](#see-the-details-of-an-image) |
| Download an image | `docker pull` | [Pull an image](#pull-an-image) |
| Use a private registry | `docker login` | [Sign in](#sign-in-to-a-private-registry) |
| Start a container from an image | `docker run` | [Run](#run-a-container-from-an-image) |
| Make an image from my code | `docker build` | [Build](#build-an-image-from-your-code) |
| Delete one image | `docker rmi` | [Delete an image](#delete-an-image) |
| Clear out old images | `docker image prune` | [Remove unused](#remove-unused-images) |

## Read the image list

The top line shows the count and the disk space, for example *12 images · 3.4 GB on disk*. Each row shows the repository, tag, image ID, size, age, and which containers use it. **Search images…** finds an image by its name, tag, or ID.

The filters help you decide what to keep:

| Filter | Shows | Good to know |
| --- | --- | --- |
| **In use** | Images a container uses, even a stopped one | You cannot delete these |
| **Unused** | Images no container uses | You can remove these, and pull them again later |
| **Untagged** | Images with no name | Usually the old version, left behind when you pulled or built the same tag again |

An image with two tags shows on two rows with the same image ID. It is one image, and it takes up space only once.

## See the details of an image

Click a row to open its details.

- **Summary:** the ID, age, size, and platform, such as `linux/amd64`.
- **Tags** and **Digests:** every name this image has.
- **Used by:** the containers that use it. Check this before you delete an image.
- **Dockerfile details:** its command, ports, volumes, work folder, user, and environment. Check **Ports** to learn which port to publish when you run it.
- **Layers:** each step that built the image, with its size.

**View raw inspect** shows the full `docker inspect` output.

![The details panel of the mysql:8.4 image, with the Summary of its ID, creation date, size, platform, and author, its Tags and Digests, the Used by list showing the running mysql-hiren container, and the View raw inspect button at the top](https://cdn.ctrlops.io/docs/docker-image-detail.webp)

Click any row in the list to open this panel. Scroll down for Dockerfile details and Layers.

## Run a container from an image

Click **Run** on the row. The [Create Container](https://ctrlops.io/docs/modules/docker/containers#run-a-container-from-an-image) form opens with the image filled in, so you only add the ports and settings it needs.

## Pull an image

### Open Pull Image

Click **Pull Image** at the top of the tab.

![The Docker Images tab with the cursor on the green Pull Image button at the top right, next to Remove unused and Create Image](https://cdn.ctrlops.io/docs/docker-click-pull-image-button.webp)

Pull Image is at the top right of the Images tab.

### Choose the registry

Pick **Docker Hub**, **GHCR**, **GitLab Registry**, **AWS ECR**, **Gitea Packages**, or **Private**. You do not need to sign in to pull a public image. For a private one, [sign in](#sign-in-to-a-private-registry) first.

![The Pull Image panel with the Registry tabs Docker Hub, GHCR, GitLab Registry, AWS ECR, Gitea Packages, and Private, the Docker Hub tab open with its account connected, the Repository and Tag fields, and the first Popular images](https://cdn.ctrlops.io/docs/docker-pull-image.webp)

Each registry has its own tab. A green line shows when you are signed in.

### Find the image

On **Docker Hub**, pick from **Popular images**, or search by name. Look for the **Docker Official Image** or **Verified publisher** badge, so you know who made it.

On the other tabs, type the name in **Repository**, such as `namespace/image`. Once you sign in, you can pick from your own repositories.

![The Docker Hub tab of Pull Image with the Repository search box, the Tag set to latest, and the Popular images cards for nginx, memcached, and busybox, each with the Docker Official Image badge, its age, pulls, and stars](https://cdn.ctrlops.io/docs/docker-popular-images.webp)

Docker Hub shows popular images first. Other registries use a name and a tag.

### Pick a tag

Choose a **Tag**. A fixed version such as `1.27` is safer for a real app than `latest`, because `latest` can change without warning.

### Pull it

Click **Pull Image**. Each step shows as it runs. When you see *Image pulled*, click **Run container** to start it right away, or close the panel to do it later.

The pull runs on the server, so you can close the panel and keep working. A **Pulls: 1** chip in the toolbar opens it again.

> If you see *This image is for arm64. The server is amd64.*, a container from this image can fail to start. Look for a tag built for your server. On Docker Hub, *Remaining pulls* shows how many you have left, and signing in raises the limit.

## Sign in to a private registry

Open the registry's tab in **Pull Image**, fill in the form, and click the login button, such as **Login to GHCR**. Create Container uses the same sign-in, so you only do this once for each server.

| Registry | What you need |
| --- | --- |
| **Docker Hub** | Your username, and a password or access token. An access token is the safer choice |
| **GHCR** | Your GitHub username and a token with `read:packages`, or **Sign in with browser** |
| **GitLab Registry** | Your username and a token with `read_registry`. For self-hosted GitLab, also change the registry host |
| **AWS ECR** | An access key ID and secret key with ECR read access, such as the `AmazonEC2ContainerRegistryReadOnly` policy |
| **Gitea Packages** | Your server's registry host, your username, and a token with `read:package` |
| **Private** | Your registry host, such as `registry.example.com:5000`, plus a username and a password or token |

**Using the Private tab?** Azure takes a service principal ID and secret. Google takes `_json_key` as the username and the JSON key as the token. Quay robot accounts use the name `org+name`.

![The GHCR tab of Pull Image saying Not connected to GHCR, with the GitHub username and Personal access token fields, the hint that the token needs the read:packages scope, the ticked Save credentials for this registry checkbox, the Login to GHCR button, and a note on where Docker keeps the login](https://cdn.ctrlops.io/docs/docker-registry-sign-in.webp)

Tick Save credentials for this registry to use the same login on your other servers.

> Docker keeps this login on the server, in the `.docker/config.json` file of your SSH user. Docker encodes that file but does not encrypt it, so use a read-only token where you can. Anyone who uses the same SSH user also gets this login.

**Save credentials for this registry** also keeps them encrypted on your computer, so **Use the saved credentials** signs you in on your other servers. **AWS ECR** keys stay on your computer: the server gets only a login that lasts 12 hours, and CtrlOps renews it before each pull.

**Log out** removes the login from this server. Pulls of private images then stop for everyone who uses that SSH user.

## Build an image from your code

Use **Create Image** when there is no ready-made image for your app. The build runs on your server, not on your computer.

### Choose the source

Click **Create Image** at the top of the tab.

![The Docker Images tab with the cursor on the Create Image button at the top right, between Remove unused and Pull Image](https://cdn.ctrlops.io/docs/docker-click-create-image-button.webp)

Create Image is next to Pull Image.

Then pick **GitHub**, **GitLab**, **Bitbucket**, **Local Upload**, or **Public repository**.

- **Git:** connect your account with a token, or with **Sign in with browser** on GitHub. Then pick the repository and branch. CtrlOps keeps the token encrypted on your computer.
- **Local Upload:** drop a folder, or a `.zip`, `.tar.gz`, or `.tar` file. CtrlOps does not send `.git` or anything in `.dockerignore`.
- **Public repository:** for a repository anyone can read. You do not need an account.

![Step 1 of the Create Image panel, with the Source, Dockerfile, and Build steps at the top and the GitHub, GitLab, Bitbucket, Local Upload, and Public repository tiles under Select a source](https://cdn.ctrlops.io/docs/docker-create-image-source.webp)

Create Image has three steps: Source, Dockerfile, and Build.

### Choose the Dockerfile

A Dockerfile is the recipe for your image. If your code has one, CtrlOps finds it and shows *Dockerfile found*. Click **Edit** to change it for this build only.

No Dockerfile? CtrlOps shows *No Dockerfile detected*. Choose how to make one:

| Option | Use it when |
| --- | --- |
| **Generate With Form** | You do not have one. Pick Node.js, Python, PHP, Go, Java, or Static site, and fill in the form |
| **Write Manually** | You want to type it yourself |
| **Upload From Local** | You have the file on your computer |

![Generate With Form selected under No Dockerfile detected, with the Dockerfile generator filled in for Node.js: base image node:20-slim, working directory /app, exposed port 3000, a RUN command, the NODE_ENV variable, and the start command, and the generated Dockerfile on the right with a Copy button](https://cdn.ctrlops.io/docs/docker-dockerfile-generator.webp)

The Dockerfile on the right changes as you fill in the form.

When it looks right, click **Generate Dockerfile** at the bottom of the form. CtrlOps puts it in the editor, so you can change it before the build.

Do not put passwords or API keys in **Environment variables** here. Anyone with the image can read them. Add them to the container when you run it.

### Build

Type the **Image name** and **Tag**, and click **Build Image**. Each layer shows as it builds.

You rarely need the other fields:

- **Build arguments** are values the Dockerfile reads while it builds.
- **Build secrets** are for passwords and tokens the build needs.
- **Advanced build options** has **Target stage**, **No cache** to build every step again, and **Always pull the base image**.

> Do not put passwords in **Build arguments**, because Docker keeps those values in the image history. Use **Build secrets** instead.

The build runs on the server, so you can close the panel and keep working. A **Builds: 1** chip in the toolbar opens it again.

When it finishes, click **Run container**. If containers already use this tag, they keep running the old image until you click **Recreate**.

> To go straight from code to a running container, use [Build from code](https://ctrlops.io/docs/modules/docker/containers#build-a-container-from-your-code) in the Containers tab. CtrlOps builds images on the server but does not push them to a registry.

## Delete an image

Click the bin icon (**Delete**) on the row, then confirm. You must pull or build the image again to use it.

- **In use:** the button is off, and it names the containers that use the image. Delete or recreate those containers first.
- **More than one tag:** the button reads **Remove tag**, and the image stays with its other tags. To remove all of it, tick the box to also remove the other tags.
- **Untagged:** you cannot pull it again, because it has no name.

## Remove unused images

Click **Remove unused** to clear out several at once. You see what it found before anything is removed, and it keeps anything a container uses.

![The Docker Images tab with the cursor on the Remove unused button at the top, next to the Search images box](https://cdn.ctrlops.io/docs/docker-click-remove-unused-button.webp)

Remove unused is at the top of the Images tab.

Only the groups with something in them show, and the arrow on a group lists its images.

| Group | Ticked at first | Worth knowing |
| --- | --- | --- |
| **Untagged images** | Yes | Usually old versions. The safest to remove |
| **Unused tagged images** | No | You must pull these again to use them |
| **Images with a digest only** | No | A compose file can name an image this way |

Type `prune` and click **Prune**. The result shows how much space you got back. To clean up containers and networks at the same time, use [Prune System](https://ctrlops.io/docs/modules/docker/dashboard#free-up-disk-space).

![The Remove unused images dialog with Untagged images ticked at 4 items, about 510 MB, Unused tagged images not ticked at 7 items, about 3.4 GB, and Images with a digest only not ticked at 2 items, about 546 MB, each unticked group with its warning, the Type prune to confirm field, and the Cancel and Prune buttons](https://cdn.ctrlops.io/docs/docker-remove-unused-images.webp)

Tick only what you want to remove. Each group shows its size.

## Tips

- **Pin a version in production.** `nginx:1.27` stays the same, and `nginx:latest` does not.
- **Check Used by before you delete.** A stopped container still counts as using an image.
- **Pull before a busy time.** A container starts faster when its image is already on the server.

## Troubleshooting

Most failures show **Show details** with the **Likely cause**, **Retry** where it helps, and **Copy report**. Send that report with any support question.

### The image does not exist, or it is private.

Check the spelling of the name and the tag. For a private image, [sign in](#sign-in-to-a-private-registry) to its registry, then try again.

### The registry refused the user name or the token.

Check both, then sign in again. Many registries need a token with the right scope in place of your password. The form names the scope.

### Docker Hub limits the pulls from this server.

Sign in to Docker Hub to get a higher limit, or wait and try again. The limit counts the pulls from this server, so other users of the server count too.

### Docker does not trust the certificate of this registry, or the registry uses HTTP.

Add the CA file to `/etc/docker/certs.d/<host>/ca.crt` on the server, or add the host to `insecure-registries` in `/etc/docker/daemon.json`.

### Use a long-term access key. Temporary keys need a session token.

AWS ECR needs a long-term key, not a temporary one. If you see *AWS refused the request time.*, check the clock of your computer.

### The token cannot read this repository.

Connect the provider again with a token that can read the repository, then click **Retry**.

### A Dockerfile step failed.

The output shows which step and why. Correct the Dockerfile, then click **Retry**. If you see *The base image is not in the registry.*, check the `FROM` line.

### The server does not have enough free space.

Builds need room on the server. Use [Prune System](https://ctrlops.io/docs/modules/docker/dashboard#free-up-disk-space) to free some, then click **Retry**.

### This server has no BuildKit.

Build secrets need BuildKit. Install the `docker-buildx` plugin on the server, or remove the build secrets.

### This login cannot use ~/.docker. Some files in it belong to root.

An older build with sudo can cause this. Click **Repair and build** to give the folder back to your login.

### CtrlOps lost the build progress.

The build is still running on the server. Click **Follow again**.

### Other images use this image as a base.

Delete the images built on top of it first, then try again.

## Frequently Asked Questions

### Do I need a Docker Hub account to pull images?

No. You can pull public images without signing in. Docker Hub limits pulls without a login, so sign in if you reach the limit or need a private image.

### Where does CtrlOps keep my registry password?

In two places, and only if you ask for the second. Docker keeps the login on the server in the `.docker/config.json` file of your SSH user, where it is encoded but not encrypted. If you tick **Save credentials for this registry**, CtrlOps also keeps them encrypted on your computer.

### Can I delete an image a container is using?

No. **Delete** is off for an image in use, and it names the containers that use it. Delete or recreate those containers first.

### Why does the same image show on two rows?

Each tag has its own row. Two rows with the same image ID are one image with two names, and it takes up space only once.

### Where does the build run?

On your server, not on your computer. CtrlOps clones your repository or uploads your files to the server and runs the build there, so the server needs enough free disk space.

### Can CtrlOps push an image to a registry?

No. CtrlOps pulls images and builds them on the server, but it does not push them to a registry. To push an image, run `docker push` in the [AI Terminal](https://ctrlops.io/docs/modules/ai-terminal).
