How to fix Conflicting options: --restart and --rm in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 253 views

The '--restart and --rm' conflict error occurs when you use both flags together in a docker run command. These options are mutually exclusive because --rm removes the container on exit while --restart keeps it alive for restarts.

Quick fix

Fixes Conflicting options: --restart and --rm

# Ephemeral container (use --rm)
docker run --rm alpine echo "Hello, World!"

# Persistent service (use --restart)
docker run -d --restart unless-stopped nginx
  1. Decide on container lifecycle behavior
  2. Remove the conflicting flag
  3. Fix docker-compose run conflicts
  4. Use docker update for existing containers
docker — error
# Ephemeral container (use --rm)
docker run --rm alpine echo "Hello, World!"
# Persistent service (use --restart)
docker run -d --restart unless-stopped nginx
Conflicting options: --restart and --rm

What this error means

The "Conflicting options: --restart and --rm" error in Docker occurs when you attempt to use both the `--restart` and `--rm` flags together in the same `docker run` command. These two flags represent fundamentally incompatible container lifecycle behaviors: - **`--rm`**: Automatically removes the container and its writable layer when the container exits. This is ideal for ephemeral containers like one-off commands, build steps, or temporary development environments. - **`--restart`**: Configures a restart policy that tells the Docker daemon to automatically restart the container after it exits. Available policies include `no`, `on-failure`, `always`, and `unless-stopped`. The conflict is logical: you cannot tell Docker to both remove the container when it exits AND restart it when it exits. If Docker removed the container, there would be nothing left to restart. Conversely, if Docker plans to restart the container, it must preserve the container state. This error is a safeguard that prevents users from creating containers with contradictory configurations that would result in undefined behavior.

Typical symptoms

  • docker run command fails immediately with 'Conflicting options: --restart and --rm'
  • Container never starts when both --rm and any --restart policy are specified
  • Scripts or automation fail when migrating from development (--rm) to production (--restart) flags
  • Docker Compose run command fails when service has restart policy defined
  • CI/CD pipeline fails during container startup step

Common causes

  1. Explicitly specifying both --rm and --restart flags in the same docker run command
  2. Running docker-compose run on a service that has a restart policy defined in docker-compose.yml
  3. Copying a docker run command and adding --rm without removing existing --restart flag
  4. Shell alias or wrapper script that includes --rm being used with commands that add --restart
  5. Misunderstanding that --restart=no is still a restart policy and conflicts with --rm

How to fix "Conflicting options: --restart and --rm"

1Decide on container lifecycle behavior

First, determine what behavior you actually need:

Use `--rm` when you want:
- One-off commands that run and clean up automatically
- Development/debugging containers that shouldn't persist
- Build steps or temporary processing containers
- Interactive shells you won't need to reconnect to

Use `--restart` when you want:
- Long-running services that should survive crashes
- Production containers that must stay running
- Background services that should start on boot
- Containers that might fail temporarily and need recovery

bash
# Ephemeral container (use --rm)
docker run --rm alpine echo "Hello, World!"

# Persistent service (use --restart)
docker run -d --restart unless-stopped nginx
2Remove the conflicting flag

Once you've decided on the lifecycle behavior, remove the conflicting flag:

If you want automatic cleanup (remove --restart):

bash
# Before (error)
docker run --rm --restart always myimage

# After (works)
docker run --rm myimage

If you want restart capability (remove --rm):

bash
# Before (error)
docker run --rm --restart always myimage

# After (works)
docker run -d --restart always myimage

Note: For detached containers (-d) that you want to restart, you almost always want --restart rather than --rm.

3Fix docker-compose run conflicts

If using docker-compose run on a service with a restart policy, the --rm flag (which is the default for docker-compose run) conflicts with the service's restart policy.

Option 1: Override the restart policy for the run command:

yaml
# docker-compose.yml
services:
  web:
    image: myimage
    restart: unless-stopped  # This causes conflict with 'run --rm'
bash
# This might fail or produce unexpected behavior
docker-compose run --rm web echo "test"

# Use docker-compose exec instead for running commands in existing containers
docker-compose exec web echo "test"

Option 2: Use docker-compose run without --rm:

bash
# Don't use --rm (container persists)
docker-compose run web echo "test"

# Clean up manually afterward
docker-compose rm -f web

Option 3: Create a separate service for one-off commands:

yaml
services:
  web:
    image: myimage
    restart: unless-stopped

  web-cli:  # For one-off commands
    image: myimage
    profiles: ["cli"]
    # No restart policy = compatible with --rm
4Use docker update for existing containers

If you have an existing container that was started with --rm and you want to add a restart policy, you cannot use docker update:

bash
# This will fail for --rm containers
docker update --restart always mycontainer
# Error: Cannot update a container with AutoRemove enabled

Instead, you must recreate the container:

bash
# Stop and remove the existing container
docker stop mycontainer
# (it auto-removes due to --rm, or manually: docker rm mycontainer)

# Create a new container with the desired restart policy
docker run -d --name mycontainer --restart unless-stopped myimage

For containers without --rm, docker update works normally:

bash
# Add restart policy to existing container
docker update --restart unless-stopped mycontainer
5Handle development vs production configurations

A common pattern is using --rm in development but --restart in production. Use environment-specific scripts or compose files:

Using shell scripts:

bash
#!/bin/bash
# run-dev.sh
docker run --rm -it -v $(pwd):/app myimage bash

# run-prod.sh
docker run -d --restart unless-stopped --name myapp myimage

Using Docker Compose override files:

yaml
# docker-compose.yml (base)
services:
  app:
    image: myimage

# docker-compose.override.yml (development - auto-loaded)
services:
  app:
    # No restart policy for development

# docker-compose.prod.yml (production)
services:
  app:
    restart: unless-stopped
bash
# Development (uses override automatically)
docker-compose up

# Production
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Advanced notes

### Restart Policy Options Explained

Docker provides four restart policies:

| Policy | Behavior |
|--------|----------|
| no | Never restart (default) |
| on-failure[:max] | Restart only on non-zero exit code, optionally with max retry count |
| always | Always restart regardless of exit code |
| unless-stopped | Like always, but don't restart if manually stopped |

Even --restart=no is technically a restart policy and will conflict with --rm, though Docker may handle this edge case differently in some versions.

### Why Docker Compose run Uses --rm by Default

The docker-compose run command is designed for one-off commands like running tests, migrations, or interactive shells. These are typically ephemeral by nature, so --rm makes sense as the default.

However, this conflicts with services that define restart policies for their long-running up behavior. The Docker Compose team addressed this in issue #3155, but the fundamental incompatibility remains.

### Alternative: Using Process Managers

If you need both automatic cleanup AND restart capability, consider using an external process manager:

bash
# Using systemd (Linux)
[Unit]
Description=My Container
After=docker.service

[Service]
ExecStartPre=-/usr/bin/docker rm -f mycontainer
ExecStart=/usr/bin/docker run --rm --name mycontainer myimage
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

This approach:
- Uses --rm so Docker cleans up the container filesystem
- Uses systemd's Restart=always to restart the entire docker run command
- Gets fresh containers on each restart (no stale state)

### Container Orchestration Considerations

In Kubernetes or Docker Swarm, this conflict doesn't exist in the same way:
- Kubernetes Pods are always ephemeral (like --rm)
- Restart behavior is controlled by the restartPolicy field in the Pod spec
- The orchestrator handles creating new container instances

This separation of concerns is one reason why orchestrators are preferred for production workloads.

Frequently asked questions

What does "Conflicting options: --restart and --rm" mean?
The "Conflicting options: --restart and --rm" error in Docker occurs when you attempt to use both the --restart and --rm flags together in the same docker run command. These two flags represent fundamentally incompatible container lifecycle behaviors: - --rm: Automatically removes the container and its writable layer when the container exits. This is ideal for ephemeral containers like one-off commands, build steps, or temporary development environments.
How do I fix "Conflicting options: --restart and --rm"?
The '--restart and --rm' conflict error occurs when you use both flags together in a docker run command. These options are mutually exclusive because --rm removes the container on exit while --restart keeps it alive for restarts.
What causes "Conflicting options: --restart and --rm"?
Explicitly specifying both --rm and --restart flags in the same docker run command Running docker-compose run on a service that has a restart policy defined in docker-compose.yml Copying a docker run command and adding --rm without removing existing --restart flag
Is the "Conflicting options: --restart and --rm" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading