Skip to content

docs(stop): say --timeout 0 is immediate SIGKILL #7215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
locker95 wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs(stop): say --timeout 0 is immediate SIGKILL #7215

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
462363d
docs(stop): say --timeout 0 is immediate SIGKILL
locker95 Aug 18, 2026
fb6d4ab
docs(stop): do not show 0 as the --timeout default
locker95 Aug 19, 2026
4547910
docs(stop): drop the 0 default from the alias man pages too
locker95 Aug 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions cli/command/container/restart.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,14 @@ func newRestartCommand(dockerCLI command.Cli) *cobra.Command {
flags := cmd.Flags()
flags.StringVarP(&opts.signal, "signal", "s", "", "Signal to send to the container")
flags.IntVarP(&opts.timeout, "timeout", "t", 0, "Seconds to wait before killing the container")
// 0 is only the Go zero value. Omitting the flag leaves timeout unset
// so the daemon uses the container or daemon default. Hide "0" from
// --help / generated docs.
flags.Lookup("timeout").DefValue = ""

// The --time option is deprecated, but kept for backward compatibility.
flags.IntVar(&opts.timeout, "time", 0, "Seconds to wait before killing the container (deprecated: use --timeout)")
flags.Lookup("time").DefValue = ""
_ = flags.MarkDeprecated("time", "use --timeout instead")

_ = cmd.RegisterFlagCompletionFunc("signal", completeSignals)
Expand Down
5 changes: 5 additions & 0 deletions cli/command/container/stop.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,14 @@ func newStopCommand(dockerCLI command.Cli) *cobra.Command {
flags := cmd.Flags()
flags.StringVarP(&opts.signal, "signal", "s", "", "Signal to send to the container")
flags.IntVarP(&opts.timeout, "timeout", "t", 0, "Seconds to wait before killing the container")
// 0 is only the Go zero value. Omitting the flag leaves timeout unset
// so the daemon uses the container or daemon default. Hide "0" from
// --help / generated docs (pflag already omits it in usage).
flags.Lookup("timeout").DefValue = ""

// The --time option is deprecated, but kept for backward compatibility.
flags.IntVar(&opts.timeout, "time", 0, "Seconds to wait before killing the container (deprecated: use --timeout)")
flags.Lookup("time").DefValue = ""
_ = flags.MarkDeprecated("time", "use --timeout instead")

_ = cmd.RegisterFlagCompletionFunc("signal", completeSignals)
Expand Down
14 changes: 9 additions & 5 deletions docs/reference/commandline/container_restart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Restart one or more containers
| Name | Type | Default | Description |
|:------------------------------------------|:---------|:--------|:---------------------------------------------|
| [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container |
| [`-t`](#timeout), [`--timeout`](#timeout) | `int` | `0` | Seconds to wait before killing the container |
| [`-t`](#timeout), [`--timeout`](#timeout) | `int` | | Seconds to wait before killing the container |


<!---MARKER_GEN_END-->
Expand Down Expand Up @@ -49,7 +49,11 @@ with a `SIGKILL` signal.
If you set `--timeout` to `-1`, no timeout is applied, and the daemon
waits indefinitely for the container to exit.

The default timeout can be specified using the [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout)
option when creating the container. If no default is configured for the container,
the Daemon determines the default, and is 10 seconds for Linux containers, and
30 seconds for Windows containers.
`--timeout 0` is not the same as omitting the flag. It skips the graceful
wait and sends `SIGKILL` immediately.

If you omit `--timeout`, the CLI does not send a timeout. The daemon
then uses the container's [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout)
if one was set, otherwise the daemon-wide
[`default-stop-timeout`](https://docs.docker.com/reference/cli/dockerd/#default-container-stop-timeout)
(10 seconds on Linux, 30 seconds on Windows).
14 changes: 9 additions & 5 deletions docs/reference/commandline/container_stop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Stop one or more running containers
| Name | Type | Default | Description |
|:------------------------------------------|:---------|:--------|:---------------------------------------------|
| [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container |
| [`-t`](#timeout), [`--timeout`](#timeout) | `int` | `0` | Seconds to wait before killing the container |
| [`-t`](#timeout), [`--timeout`](#timeout) | `int` | | Seconds to wait before killing the container |


<!---MARKER_GEN_END-->
Expand Down Expand Up @@ -55,7 +55,11 @@ with a `SIGKILL` signal.
If you set `--timeout` to `-1`, no timeout is applied, and the daemon
waits indefinitely for the container to exit.

The default timeout can be specified using the [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout)
option when creating the container. If no default is configured for the container,
the Daemon determines the default, and is 10 seconds for Linux containers, and
30 seconds for Windows containers.
`--timeout 0` is not the same as omitting the flag. It skips the graceful
wait and sends `SIGKILL` immediately.

If you omit `--timeout`, the CLI does not send a timeout. The daemon
then uses the container's [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout)
if one was set, otherwise the daemon-wide
[`default-stop-timeout`](https://docs.docker.com/reference/cli/dockerd/#default-container-stop-timeout)
(10 seconds on Linux, 30 seconds on Windows).
2 changes: 1 addition & 1 deletion docs/reference/commandline/restart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Restart one or more containers
| Name | Type | Default | Description |
|:------------------|:---------|:--------|:---------------------------------------------|
| `-s`, `--signal` | `string` | | Signal to send to the container |
| `-t`, `--timeout` | `int` | `0` | Seconds to wait before killing the container |
| `-t`, `--timeout` | `int` | | Seconds to wait before killing the container |


<!---MARKER_GEN_END-->
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/commandline/stop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Stop one or more running containers
| Name | Type | Default | Description |
|:------------------|:---------|:--------|:---------------------------------------------|
| `-s`, `--signal` | `string` | | Signal to send to the container |
| `-t`, `--timeout` | `int` | `0` | Seconds to wait before killing the container |
| `-t`, `--timeout` | `int` | | Seconds to wait before killing the container |


<!---MARKER_GEN_END-->
Expand Down