Switch Docker's Default Context Without Losing Track of Overrides

You will switch the Docker CLI to a named context, verify the endpoint it selects, and return to the previous context without guessing which daemon a later command will reach. The installed command checked for this guide is Docker Community CLI 29.8.1 from package docker-ce-cli version 5:29.8.1-1~ubuntu.24.04~noble.

Allow about ten minutes. You need the Docker CLI and at least one context that already exists. This guide does not create, delete or edit contexts, and it does not start or stop containers. You normally do not need sudo: context selection is client configuration, not a daemon administration operation.

1. Check the command and list available contexts

First confirm that the installed CLI has the subcommand and see the contexts available to your current Docker configuration:

$ docker --version
Docker version 29.8.1, build 4a63305
$ docker context use --help
Usage:  docker context use CONTEXT

Set the default docker context
$ docker context ls
NAME        DESCRIPTION                               DOCKER ENDPOINT               ERROR
default *   Current DOCKER_HOST based configuration   unix:///var/run/docker.sock

Your list will differ. The asterisk identifies the context selected by the CLI at that moment. Copy a context name exactly, including capitalisation if your installation uses one. A context can describe a local Unix socket or a remote endpoint, so choosing one can send later commands to a different machine.

2. Inspect the target before switching

Replace CONTEXT_NAME with an existing name from docker context ls. Inspection is read-only and shows the Docker endpoint associated with that context:

$ docker context inspect CONTEXT_NAME
[
    {
        "Name": "CONTEXT_NAME",
        "Metadata": {},
        "Endpoints": {
            "docker": {
                "Host": "unix:///var/run/docker.sock",
                "SkipTLSVerify": false
            }
        }
    }
]

The endpoint and the rest of the record are installation-specific. Treat a remote host, a non-standard socket or SkipTLSVerify: true as a deliberate security boundary. Stop here if you cannot identify the machine or trust model represented by the endpoint.

The exact JSON can include additional fields, such as storage paths or TLS material. The point of this check is to identify the destination, not to edit the JSON by hand. Context data belongs to the Docker CLI configuration and should be changed through Docker commands.

3. Make the default switch

Run the command with the exact context name:

$ docker context use CONTEXT_NAME
CONTEXT_NAME
Current context is now "CONTEXT_NAME"

The command updates the Docker CLI's persistent default in the active client configuration, normally under ~/.docker/config.json. It affects later shells that use the same Docker configuration, not just the terminal in which you ran it. The command selects a client endpoint; it does not migrate containers, copy images or alter the daemon.

This is the point at which a typo matters. An unknown name fails instead of creating a new context:

$ docker context use definitely-not-a-context
context "definitely-not-a-context" does not exist

Error wording can vary slightly by CLI build. A non-zero status and a message saying that the context does not exist mean the default was not changed.

4. Verify both the name and the endpoint

Check the selected name first, then confirm the asterisk and endpoint:

$ docker context show
CONTEXT_NAME
$ docker context ls
NAME           DESCRIPTION   DOCKER ENDPOINT                 ERROR
default                      unix:///var/run/docker.sock
CONTEXT_NAME                 ssh://user@example-host *

Output is host-specific, and the columns may be wider than this example. The useful checks are that docker context show prints the intended name, the same row has *, and inspection shows the intended endpoint. If the context points at a remote daemon, do not treat a successful name check as proof that the remote daemon is reachable. A later Docker operation still needs valid credentials, network access and daemon availability.

For a harmless connectivity check, use an operation appropriate to your environment, such as:

$ docker version
Client:
 Version:           29.8.1
...
Server:
 Engine:
  Version:          29.x.y
...

This may contact the daemon and can fail without indicating that context selection failed. Do not use a command that creates, removes or changes resources merely to test connectivity.

5. Understand the overrides that can make a switch look broken

docker context use sets the default, but the default is not always the effective choice. Docker documents three common overrides:

• DOCKER_CONTEXT selects a context for the current environment and takes precedence over the configured default.
• DOCKER_HOST selects a daemon host directly, which can prevent the selected context from being the endpoint you expect.
• The global docker --context OTHER_CONTEXT ... option selects a context for one command.

Check the first two variables without printing unrelated environment data:

$ printf 'DOCKER_CONTEXT=%s\n' "${DOCKER_CONTEXT-<unset>}"
DOCKER_CONTEXT=<unset>
$ printf 'DOCKER_HOST=%s\n' "${DOCKER_HOST-<unset>}"
DOCKER_HOST=<unset>

If an override is present, the selected context name can be correct while Docker commands still use another destination. For a temporary shell test, remove an override only if you understand why it was set:

$ unset DOCKER_CONTEXT DOCKER_HOST
$ docker context show
CONTEXT_NAME

unset changes only the current shell. A new shell will receive its variables again if they come from a shell profile, service environment or automation. Review that source rather than repeatedly switching contexts.

6. Switch back or avoid a persistent change

To undo the persistent selection, use the context you recorded in step 1. The standard local context is usually named default:

$ docker context use default
default
Current context is now "default"
$ docker context show
default

Do not assume default is the right recovery target on a managed workstation. Use the earlier docker context ls result, then verify the endpoint again.

For one-off work, avoid changing the default at all:

$ docker --context CONTEXT_NAME ps
CONTAINER ID   IMAGE   COMMAND   CREATED   STATUS   PORTS   NAMES

An empty table can be a valid result. The command targets the named context for that invocation and leaves the persistent default alone. If the command should use a context only for the current shell, set DOCKER_CONTEXT and remove it afterwards:

$ export DOCKER_CONTEXT=CONTEXT_NAME
$ docker context show
CONTEXT_NAME
$ unset DOCKER_CONTEXT