Update a Docker Context with docker context update

The production host moved, the certificates were reissued, and now half the team has a context pointing at nothing. docker context update fixes the saved settings in place, and this guide shows how to do it without losing the endpoint.

You will change an existing context's description or Docker endpoint, then confirm the stored values before using it. Allow about ten minutes for a description-only change, or longer if you need to check TLS material with the context owner. The examples use Docker CE CLI 29.8.1, installed from the docker-ce-cli package on this machine.

1. Find the context you intend to change

A context is a named set of client connection settings. Updating one changes the saved configuration for every later command that selects it. It does not create a context and it does not switch the current context.

Start by listing the names and checking which one has the asterisk:

$ docker context ls
NAME        DESCRIPTION                               DOCKER ENDPOINT
default *   Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
production                                            tcp://docker.example.test:2376

Replace production below with the exact name from your own output. Do not guess a context name, especially before changing a remote endpoint. Check its current configuration as a checkpoint:

$ docker context inspect production
[
    {
        "Name": "production",
        "Endpoints": {
            "docker": {
                "Host": "tcp://docker.example.test:2376",
                "SkipTLSVerify": false
            }
        }
    }
]

The full inspection also shows metadata and paths to stored context material.

2. Change only the description

For a label change, use --description and the context name. This does not alter where Docker connects:

$ docker context update production \
    --description "Production Docker host"
production
Successfully updated context "production"

Verify the metadata and endpoint separately:

$ docker context inspect production \
    --format '{{.Name}}: {{.Metadata.Description}} - {{.Endpoints.docker.Host}}'
production: Production Docker host - tcp://docker.example.test:2376

If the description contains spaces, keep the quotes. An empty description is accepted by the CLI syntax, but it removes useful identification, so use a deliberate label rather than relying on the command's default.

3. Change the Docker endpoint deliberately

The --docker option takes comma-separated key-value settings. The installed manpage documents from, host, ca, cert, key and skip-tls-verify. A local socket change looks like this:

$ docker context update production \
    --docker "host=unix:///var/run/docker.sock"
production
Successfully updated context "production"

For a TLS endpoint, provide the complete set of values you intend to use:

$ docker context update production \
    --docker "host=tcp://docker.example.test:2376,ca=/path/to/ca.pem,cert=/path/to/client-cert.pem,key=/path/to/client-key.pem"
production
Successfully updated context "production"

Use real paths, not the placeholders. Docker's own example shows a tilde in a path, but quoting and shell expansion are easy to misread in scripts, so an absolute path is clearer.

Docker stores endpoint settings in the context. It does not make a remote daemon reachable, repair certificates or grant your user access to a socket.

4. Treat TLS bypass as an emergency setting

skip-tls-verify=true disables certificate validation for that context. That can expose credentials and Docker control traffic to an impostor endpoint.

$ docker context update production \
    --docker "host=tcp://docker.example.test:2376,skip-tls-verify=true"
production
Successfully updated context "production"

$ docker context inspect production \
    --format '{{json .Endpoints.docker}}'
{"Host":"tcp://docker.example.test:2376","SkipTLSVerify":true}

This is a security-sensitive change, not a harmless connectivity option. Prefer fixing the CA and client certificate paths, then set skip-tls-verify=false or replace the endpoint settings with the verified TLS values.

5. Check which context your next command will use

docker context update does not select the context. The current selection can still be default, while DOCKER_CONTEXT or the global --context option can override it for a command. Check before running anything that creates, removes or inspects containers:

$ docker context show
default
$ docker --context production info

The info command may produce a long response and requires a reachable daemon. To check the saved endpoint without connecting, use docker context inspect as above.

6. Undo a mistaken update

There is no separate undo flag. Restore the values you recorded before the update. This example puts the context back on its TLS endpoint with the old certificate files, sets the original description and re-enables certificate validation:

$ docker context update production \
    --description "Original production context" \
    --docker "host=tcp://docker.example.test:2376,ca=/path/to/old-ca.pem,cert=/path/to/old-cert.pem,key=/path/to/old-key.pem,skip-tls-verify=false"
production
Successfully updated context "production"

$ docker context inspect production \
    --format '{{json .Endpoints.docker}}'
{"Host":"tcp://docker.example.test:2376","SkipTLSVerify":false}

7. Diagnose the usual failures

• Context does not exist. The name is wrong, or the command is reading a different Docker configuration. Compare docker context ls with docker context show, and check whether DOCKER_CONFIG is set.
• Update succeeded but docker info fails. The saved endpoint, network route, daemon or credentials are wrong. It does not mean the update syntax failed.
• A value contains a comma. Shell quoting alone is not enough to make it one Docker key-value value, because Docker uses commas to separate the endpoint fields. Keep paths and values simple, and verify the resulting JSON after every endpoint update.

If only the description changed, inspect the endpoint too. The safest checkpoint proves both the field you meant to change and the connection target you meant to preserve.