Prepare a Docker Container Without Starting It

You will use docker create to make a container definition, check that Docker recorded the settings you intended, start it as a separate decision, and remove the test container without leaving an unused object behind. The command creates a container from an image but does not start it. This guide follows the installed Docker Community CLI 29.8.1 and its docker-create(1) manpage.

Allow about fifteen minutes. You need a working Docker daemon, permission to use it, and an image that is already present locally. On this host, ordinary Docker commands work without sudo. If your account is not allowed to access the daemon, use the privilege method approved by your administrator. Adding yourself to the docker group grants broad control over the host, so do not make that change casually.

1. Check the command and choose an image

Start with read-only checks. They confirm the installed syntax and show which images are available without creating anything:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker create --help | sed -n '1,8p'
Usage:  docker create [OPTIONS] IMAGE [COMMAND] [ARG...]

Create a new container

Aliases:
  docker container create, docker create
$ docker image ls --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}'
REPOSITORY   TAG       IMAGE ID
alpine       3.22      4bcff6393c88

The image list is host-specific. Select an image that already exists, then assign it to a shell variable. The --pull=never option in the examples below prevents an accidental download. If the selected image is absent, the command stops with an error instead of changing the daemon state.

$ IMAGE_NAME='alpine:3.22'
$ docker image inspect "$IMAGE_NAME" --format '{{.RepoTags}}'
[alpine:3.22]

Checkpoint: the inspect command should print the exact image tag you chose. Replace the example value with a tag from your own docker image ls output; do not copy the sample image ID as if it were universal.

2. Create a stopped container definition

Creating a container is a state-changing operation. Docker adds a writable container layer and records the requested configuration, but the container remains stopped with a created status. The following command gives it a predictable name, keeps standard input open, allocates a pseudo-terminal, and sets a harmless command that will print one line when started:

$ docker create \
    --pull=never \
    --name guide-create-demo \
    --interactive --tty \
    "$IMAGE_NAME" \
    /bin/sh -c 'printf "%s\n" container-started'
6f2c7a0b0f4c...

The identifier is truncated here because Docker prints a full, host-specific ID. A name makes later commands easier to read. If the name is already in use, Docker refuses to overwrite the existing container. Inspect or remove that existing object only after confirming it is yours.

Verify the result before starting anything:

$ docker container inspect --format 'name={{.Name}} status={{.State.Status}} image={{.Config.Image}}' guide-create-demo
name=/guide-create-demo status=created image=alpine:3.22
$ docker ps --all --filter name=guide-create-demo --format 'table {{.Names}}\t{{.Status}}'
NAMES              STATUS
guide-create-demo  Created

Checkpoint: the status must be created, not Up. If it is running, you are looking at a different container or command. docker create itself does not run the image's entrypoint or command.

3. Understand where the command and arguments go

The syntax is docker create [OPTIONS] IMAGE [COMMAND] [ARG...]. Docker reads options before the image. The first word after the image replaces the image's default command, while the remaining words become its arguments. In the example, /bin/sh is the command and -c plus the format string are its arguments.

Use --entrypoint when you need to replace the image's configured entrypoint separately. Do not append options intended for Docker after the image: they will normally be passed to the container command instead. Keep shell quoting visible when a value contains spaces or shell punctuation.

$ docker create --pull=never \
    --name guide-command-demo \
    "$IMAGE_NAME" \
    --entrypoint /bin/sh

This second example is only useful for showing the option boundary, so remove it when finished:

$ docker rm guide-command-demo
guide-command-demo

4. Add configuration you can inspect

Most practical use of create is preparing settings for a later start. Environment variables, a working directory, a restart policy, a read-only root filesystem, and port mappings can all be recorded at creation time:

$ docker create \
    --pull=never \
    --name guide-config-demo \
    --env APP_MODE='test' \
    --workdir /tmp \
    --read-only \
    --tmpfs /tmp \
    --publish 127.0.0.1:18080:8080 \
    "$IMAGE_NAME" \
    /bin/sh -c 'printf "%s\n" "$APP_MODE"'
9a0b...

The port mapping reserves a host-to-container forwarding rule in the container configuration. It does not make a service listen, because the container has not started. Binding to 127.0.0.1 keeps the example local to the host. If you bind to all host interfaces, the service may become reachable from the network, so choose that deliberately.

Inspect selected fields rather than guessing that an option was accepted:

$ docker inspect --format 'status={{.State.Status}} read-only={{.HostConfig.ReadonlyRootfs}} ports={{json .HostConfig.PortBindings}} env={{json .Config.Env}}' guide-config-demo
status=created read-only=true ports={"8080/tcp":[{"HostIp":"127.0.0.1","HostPort":"18080"}]} env=["APP_MODE=test"]

The exact JSON formatting can vary between CLI and daemon versions. The useful checks are the values, not whitespace or field ordering.

5. Start it only after the inspection checkpoint

Starting is a separate, potentially service-disrupting action. Before doing it, check the image command, mounts, environment, network exposure and privilege-related options. Do not use --privileged, --device, --cap-add or --use-api-socket merely to make an example work. These options can expand access to the host or Docker daemon and need a specific operational reason.

For the harmless first container, start it attached so its one-line output is visible:

$ docker start --attach --interactive guide-create-demo
container-started

It exits immediately because its command runs printf. Check its final state and recorded output:

$ docker inspect --format 'status={{.State.Status}} exit={{.State.ExitCode}}' guide-create-demo
status=exited exit=0
$ docker logs guide-create-demo
container-started

If you want a container to be removed automatically after it exits, include --rm when creating it. That is convenient for disposable jobs, but it removes the container and associated anonymous volumes after exit, so do not use it when you need post-run inspection.

6. Remove the objects you created

Removal is irreversible for the container's writable layer and its local metadata. Confirm the names first, then remove only the named demonstration containers:

$ docker ps --all --filter name='guide-' --format '{{.Names}}\t{{.Status}}'
guide-create-demo   Exited (0) ...
guide-config-demo   Created
$ docker rm guide-create-demo guide-config-demo
guide-create-demo
guide-config-demo

If a container is still running, plain docker rm refuses unless you add --force. Prefer stopping it and then removing it, especially for a real service. A forced removal stops the container and deletes its metadata, which can interrupt work:

$ docker stop guide-create-demo
$ docker rm guide-create-demo

Checkpoint: an empty result confirms that the names are gone:

$ docker ps --all --filter name='guide-' --format '{{.Names}}'