Tutorial de parâmetros do docker run: veja os resultados na prática

docker run é o comando mais usado do Docker e também o que tem mais parâmetros. O formato básico é:

docker run [opções] imagem[:tag] [comando] [argumentos do comando]

O conteúdo após o nome da imagem substitui o comando padrão da imagem (CMD):

$ docker run --rm alpine:3.23 cat /etc/alpine-release
3.23.6

--rm é um parâmetro do Docker; cat /etc/alpine-release é o comando executado dentro do contêiner e substitui o /bin/sh padrão do alpine.

Os parâmetros precisam vir antes do nome da imagem

Tudo o que vier depois do nome da imagem será tratado como um comando dentro do contêiner:

$ docker run alpine:3.23 --rm echo hi
docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: exec: "--rm": executable file not found in $PATH

Run 'docker run --help' for more information

O Docker tenta executar no contêiner um programa chamado --rm e, claro, não o encontra (executable file not found). Ao ver esse tipo de erro, confira primeiro a posição dos parâmetros.

Modo de execução

docker run -it --rm ubuntu:26.04 bash      # entra interativamente e remove ao sair
docker run -d --name cache redis:8-alpine  # serviço em segundo plano

-it quase sempre é usado em conjunto para abrir um shell interativo. Com apenas -i, você pode enviar dados ao contêiner por um pipe:

$ echo "hello" | docker run -i --rm alpine:3.23 cat
hello

Portas: -p

O formato é -p porta-do-host:porta-do-contêiner. Veja a comparação prática destas três formas:

$ docker run -d --name p1 -p 8080:80 nginx:1.30
27b89a4fae92dfe05bf051e11700033c7b9bb71f8747acc986d2a535cc1baa00

$ docker run -d --name p2 -p 127.0.0.1:8081:80 nginx:1.30
3327f3c1df4fa1e03fa3a120e5d889859fc0cb53d0aaf269826c81b25f4411c2

$ docker run -d --name p3 -P nginx:1.30
57c9a309c4758786361738b7b9a4231f404cb9bbab28f38cad39b4b6e996d9e0

$ docker port p1
80/tcp -> 0.0.0.0:8080
80/tcp -> [::]:8080

$ docker port p2
80/tcp -> 127.0.0.1:8081

$ docker port p3
80/tcp -> 0.0.0.0:32768
80/tcp -> [::]:32768

docker port nome-do-contêiner mostra o mapeamento efetivo. Para uma porta UDP, escreva -p 5353:53/udp.

Em um host na nuvem, -p 8080:80 permite conexões externas. Além disso, o Docker altera as regras do firewall, então as configurações do ufw talvez não consigam bloquear o acesso. Para serviços que não devem ficar expostos, como bancos de dados, vincule a porta a 127.0.0.1 ou simplesmente não use -p; use uma rede personalizada para conectar os contêineres entre si.

Dados: -v e --mount

-v caminho-no-host:caminho-no-contêiner monta uma pasta do host no contêiner (bind mount). Prepare uma pasta site com um arquivo index.html:

$ ls site
index.html

$ docker run -d --name site -p 8080:80 -v "$(pwd)/site:/usr/share/nginx/html:ro" nginx:1.30
e91f46b91ff8f0f64d59d6605bfddea0ee5bca809de86d81cbd5051815e65dd1

$ curl -s http://localhost:8080 | head -n 3
<!doctype html>
<html><head><meta charset="utf-8"><title>My site</title>
<style>body{font-family:system-ui,sans-serif;max-width:640px;margin:60px auto;padding:0 16px;color:#1f2937}h1{color:#1d63ed}</style></head>

Comando equivalente no Windows (selecione uma aba para alternar):

docker run -d --name site -p 8080:80 -v "$(pwd)/site:/usr/share/nginx/html:ro" nginx:1.30

docker run -d --name site -p 8080:80 -v "${PWD}/site:/usr/share/nginx/html:ro" nginx:1.30

docker run -d --name site -p 8080:80 -v "%cd%/site:/usr/share/nginx/html:ro" nginx:1.30

O :ro no final significa somente leitura. Se você tentar gravar nessa pasta dentro do contêiner, a operação será recusada:

$ docker exec site sh -c "echo test > /usr/share/nginx/html/x.txt"
sh: 1: cannot create /usr/share/nginx/html/x.txt: Read-only file system

Outra forma de montagem é usar um Volume gerenciado pelo Docker (-v nome:caminho-no-contêiner), adequado para guardar dados como os de um banco de dados:

docker run -d -v pgdata:/var/lib/postgresql postgres:18

--mount oferece uma forma mais longa, mas mais explícita. Para ver as diferenças e quando usar cada opção, consulte Volume e Bind Mount.

Variáveis de ambiente: -e e --env-file

$ docker run --rm -e GREETING=hello -e APP_ENV=dev alpine:3.23 env
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=18f035817c43
GREETING=hello
APP_ENV=dev
HOME=/root

-e NOME_DA_VARIÁVEL (sem informar um valor) usa o valor atual da variável de ambiente homônima no host:

$ APP_ENV=prod docker run --rm -e APP_ENV alpine:3.23 sh -c 'echo $APP_ENV'
prod

Se houver muitas variáveis, use --env-file arquivo. Consulte Variáveis de ambiente e arquivo .env para saber mais.

Rede

Contêineres na mesma rede personalizada podem se conectar uns aos outros pelo nome do contêiner:

$ docker network create mynet
2ecd542737519b0b8919061077814e007a72e2d07973f0840608b1b5454c678e

$ docker run -d --name myweb --network mynet nginx:1.30
9a6ca3dca3a003e28b9870f3eec436cf7023a6872e8ddd4cee971d29f845583b

$ docker run --rm --network mynet alpine:3.23 ping -c 2 myweb
PING myweb (172.19.0.2): 56 data bytes
64 bytes from 172.19.0.2: seq=0 ttl=64 time=0.094 ms
64 bytes from 172.19.0.2: seq=1 ttl=64 time=0.064 ms

--- myweb ping statistics ---
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 0.064/0.079/0.094 ms

$ docker run --rm alpine:3.23 ping -c 1 -W 2 myweb
ping: bad address 'myweb'

• O primeiro contêiner executa o ping na rede mynet, e o DNS integrado do Docker resolve myweb para 172.19.0.2.
• O segundo não usa --network e, na rede padrão, não encontra myweb (bad address).

Evite usar nomes de contêiner como web e app, que por acaso são palavras usadas como domínios de nível superior (TLD). Sem entrar na mesma rede, esses nomes podem ser resolvidos pelo DNS externo para endereços estranhos (como 127.0.53.53), o que dificulta ainda mais a depuração.

docker run --network host nginx:1.30     # Use the host network directly (Linux)
docker run --network none alpine:3.23    # No network at all

Veja Redes e comunicação entre contêineres.

Política de reinicialização

docker run -d --restart unless-stopped nginx:1.30

Os valores disponíveis são no, on-failure, always e unless-stopped. Veja o comportamento de cada um em Ciclo de vida do contêiner.

Limites de recursos

$ docker run -d --name limited --memory 64m --cpus 0.5 nginx:1.30
2e65ce89f346cb7d9d57f1e6ad529d63ad53d1d914b6d3178dc3344a1d3325f0

$ docker stats --no-stream limited
CONTAINER ID   NAME      CPU %     MEM USAGE / LIMIT   MEM %     NET I/O       BLOCK I/O         PIDS
2e65ce89f346   limited   0.00%     3.922MiB / 64MiB    6.13%     736B / 126B   1.77MB / 8.19kB   2

MEM USAGE / LIMIT mostra 3.922MiB / 64MiB, indicando que o limite de memória está ativo. Quando ocioso, o nginx usa menos de 4 MB.

Para ver o que acontece quando o limite de memória é excedido, consulte o exemplo de OOM em Como ver logs e depurar.

Substituir os valores padrão da imagem

$ docker run --rm --entrypoint sh nginx:1.30 -c "nginx -v; whoami"
nginx version: nginx/1.30.5
root

$ docker run --rm -u 1000:1000 alpine:3.23 id
uid=1000 gid=1000 groups=1000

$ docker run --rm -w /tmp alpine:3.23 pwd
/tmp

$ docker run --rm -h myhost alpine:3.23 hostname
myhost

Use -u para que os arquivos criados pelo contêiner pertençam a você, e não ao root:

docker run --rm -u "$(id -u):$(id -g)" -v "$(pwd):/work" -w /work node:24-alpine npm install

Sistema de arquivos somente leitura

$ docker run --rm --read-only alpine:3.23 touch /hello
touch: /hello: Read-only file system

--read-only torna somente leitura todo o sistema de arquivos do contêiner. Mesmo que o programa seja comprometido, ele não poderá modificar arquivos. Libere a escrita apenas onde for necessário, usando --tmpfs /tmp ou um Volume. Veja Práticas recomendadas de segurança.

Outros parâmetros úteis

Mais opções para consulta rápida

A tabela a seguir foi organizada com base em docker run --help (Docker 29) e reúne opções úteis que não são apresentadas em detalhes neste capítulo. Para ver a lista completa, execute docker run --help.

Exemplos de combinações comuns

# 1. Contêiner de ferramenta temporário: execute um comando na pasta atual
docker run --rm -v "$(pwd):/data" -w /data alpine:3.23 ls -la

# 2. Banco de dados para desenvolvimento local, acessível somente pelo host local
docker run -d --name devdb --restart unless-stopped \
  -p 127.0.0.1:5432:5432 \
  -e POSTGRES_PASSWORD=dev \
  -v devdb:/var/lib/postgresql \
  postgres:18

# 3. Serviço em produção com limites de recursos e tamanho dos logs
docker run -d --name api --restart unless-stopped \
  --memory 1g --cpus 2 \
  --log-opt max-size=10m --log-opt max-file=3 \
  --env-file .env -p 3000:3000 \
  myorg/api:1.4.2

# 1. Contêiner de ferramenta temporário: execute um comando na pasta atual
docker run --rm -v "${PWD}:/data" -w /data alpine:3.23 ls -la

# 2. Banco de dados para desenvolvimento local, acessível somente pelo host local
docker run -d --name devdb --restart unless-stopped `
  -p 127.0.0.1:5432:5432 `
  -e POSTGRES_PASSWORD=dev `
  -v devdb:/var/lib/postgresql `
  postgres:18

# 3. Serviço em produção com limites de recursos e tamanho dos logs
docker run -d --name api --restart unless-stopped `
  --memory 1g --cpus 2 `
  --log-opt max-size=10m --log-opt max-file=3 `
  --env-file .env -p 3000:3000 `
  myorg/api:1.4.2

# 1. Contêiner de ferramenta temporário: execute um comando na pasta atual
docker run --rm -v "%cd%:/data" -w /data alpine:3.23 ls -la

# 2. Banco de dados para desenvolvimento local, acessível somente pelo host local
docker run -d --name devdb --restart unless-stopped ^
  -p 127.0.0.1:5432:5432 ^
  -e POSTGRES_PASSWORD=dev ^
  -v devdb:/var/lib/postgresql ^
  postgres:18

# 3. Serviço em produção com limites de recursos e tamanho dos logs
docker run -d --name api --restart unless-stopped ^
  --memory 1g --cpus 2 ^
  --log-opt max-size=10m --log-opt max-file=3 ^
  --env-file .env -p 3000:3000 ^
  myorg/api:1.4.2

Quando há muitas opções, fica difícil manter o comando. Para executar algo por bastante tempo ou operar vários contêineres juntos, recomendamos usar Docker Compose e registrar as configurações em um arquivo.

Resumo

• Escreva as opções antes do nome da imagem. O que vier depois é o comando a ser executado dentro do contêiner.
• -d, --rm, --name, -p, -v e -e são as opções mais usadas em conjunto.
• --memory, --cpus e --pids-limit limitam os recursos.
• --entrypoint, -u e -w substituem os valores padrão da imagem.

Exercícios

Exercício 1: Escreva um comando que execute nginx:1.30-alpine em segundo plano, com o nome site, permita conexões à porta 8080 somente pelo host local, limite a memória a 128 MB e não mantenha o contêiner depois que ele terminar.

docker run -d --rm --name site -p 127.0.0.1:8080:80 --memory 128m nginx:1.30-alpine

Exercício 2: O ENTRYPOINT da imagem postgres:18 inicia o banco de dados. Como você pode acessar somente o shell, sem iniciar o banco de dados?

docker run --rm -it --entrypoint sh postgres:18

Atualizado 14 de outubro de 2026