Introduction

Running docker container run without specifying an image produces the error "docker container run requires at least 1 argument." This is one of the most common Docker errors newcomers encounter, and the fix is straightforward: you must always provide an image name. This article explains the command syntax, shows practical examples, and covers related mistakes that produce the same or similar errors.

Understanding the Command

docker container run (or its shorthand docker run) creates a new container from an image and starts it. The image name is the one required argument because Docker needs to know which filesystem and configuration to use as the container's base.

The full syntax is:

docker container run [OPTIONS] IMAGE [COMMAND] [ARG...]

• IMAGE is required. It specifies the base image (for example, nginx, python:3.12, or ubuntu:22.04).
• OPTIONS are optional flags placed before the image name.
• COMMAND and ARG... are optional and override the default command defined in the image.

Basic Examples

Running a simple container

docker container run ubuntu:22.04 echo "Hello from Ubuntu"

This pulls the ubuntu:22.04 image if it is not already present locally, creates a container, runs the echo command inside it, and then exits.

Running an interactive shell

docker container run -it alpine sh

The -i flag keeps STDIN open, and -t allocates a pseudo-TTY. Together, they give you an interactive shell session inside the container.

Running a background service

docker container run -d -p 8080:80 --name my-web nginx:latest

This starts an Nginx container in detached mode (-d), maps host port 8080 to container port 80, and gives the container the name my-web.

Running with environment variables

1docker container run -d \
2  -p 5432:5432 \
3  -e POSTGRES_USER=admin \
4  -e POSTGRES_PASSWORD=secret \
5  -e POSTGRES_DB=myapp \
6  postgres:16

Each -e flag sets an environment variable inside the container. This is the standard way to pass configuration to containerized services.

Common Causes of the Error

Missing image name entirely

# This produces the error
docker container run -d -p 8080:80

Docker interprets the flags but finds no positional argument for the image. Always place the image name after all options.

Placing the image name before options

# This will not work as expected
docker container run nginx -d -p 8080:80

Docker treats nginx as the image and -d -p 8080:80 as the command to run inside the container. The command fails because there is no -d binary in the Nginx image. Options must come before the image name.

Typos in multi-line commands

When using line continuation with backslashes, a missing backslash causes the shell to execute a partial command.

1# Broken: missing backslash after -d
2docker container run -d
3  -p 8080:80 \
4  nginx:latest

The shell runs docker container run -d on the first line, which lacks an image argument. Add the backslash after -d to continue the command on the next line.

1# Fixed
2docker container run -d \
3  -p 8080:80 \
4  nginx:latest

Confusing docker container run with docker container exec

docker container exec runs a command in an already-running container and requires a container name or ID plus a command. If you accidentally type run when you mean exec, or vice versa, you get unexpected errors.

1# Run a command inside an existing container
2docker container exec my-web nginx -t
3
4# Create and start a new container (needs an image)
5docker container run nginx:latest nginx -t

Useful Flags Reference

Here are commonly used flags for docker container run:

1# Mount a volume
2docker container run -v /host/path:/container/path nginx
3
4# Set a restart policy
5docker container run --restart unless-stopped redis
6
7# Limit memory
8docker container run --memory 512m python:3.12 python script.py
9
10# Set the working directory
11docker container run -w /app node:20 npm start
12
13# Remove the container after it exits
14docker container run --rm ubuntu:22.04 date

The --rm flag is especially useful during development and testing because it automatically removes the container when it stops, preventing a buildup of exited containers.

Verifying and Managing Containers

After running a container, you can check its status and inspect it.

1# List running containers
2docker container ls
3
4# List all containers including stopped ones
5docker container ls -a
6
7# View container logs
8docker container logs my-web
9
10# Inspect container configuration
11docker container inspect my-web
12
13# Stop a running container
14docker container stop my-web
15
16# Remove a stopped container
17docker container rm my-web

Common Pitfalls

• Forgetting the image name is the most common cause of the "requires at least 1 argument" error. Double-check that the image name appears after all flags.
• Placing flags after the image name. Docker interprets anything after the image as the command to execute inside the container, not as Docker options.
• Missing backslashes in multi-line shell commands. Each line except the last must end with \ for the shell to treat it as a single command.
• Using docker run and docker container run interchangeably is fine, since they are aliases, but mixing them with docker create and docker start (which are separate steps) can cause confusion.
• Not specifying an image tag defaults to :latest, which may pull a different version than expected. Pin your image versions in production.

Summary

The "docker container run requires at least 1 argument" error means you forgot to specify an image name. The fix is to include the image as the first positional argument after all options. Remember that options go before the image name, the command to run inside the container goes after it, and multi-line commands need proper backslash continuation. Use docker container ls -a to check your containers and --rm to auto-clean during development.