Import a Docker Context Safely from an Archive

You will import a context exported by Docker, check the endpoint and leave the active context unchanged until you deliberately choose to use it. The installed command is Docker CE CLI 29.8.1 from package docker-ce-cli version 5:29.8.1-1~ubuntu.24.04~noble. Allow about ten minutes if the archive is already on disk.

A Docker context is client-side connection configuration. Importing one writes Docker CLI configuration under the current DOCKER_CONFIG; it does not start a daemon or switch the active context. The archive can contain endpoint details and TLS material, so only import a file from a source you trust.

1. Check the command and your current contexts

Confirm that this Docker client has the subcommand, then record the current list before changing local configuration:

$ docker context import --help
Usage:  docker context import CONTEXT FILE|-

Import a context from a tar or zip file
$ docker context ls
NAME        DESCRIPTION                               DOCKER ENDPOINT               ERROR
default *   Current DOCKER_HOST based configuration   unix:///var/run/docker.sock

The asterisk marks the active context. The import command itself has no import-specific options in the installed manual page. It takes the new context name and either an archive pathname or - for standard input.

Checkpoint: keep the output of docker context ls. You will use it to confirm that the new context was added without changing the asterisk.

2. Inspect the archive before importing it

Do not feed an unknown archive straight to Docker. First check its type and listing. Replace the placeholder with the file you received:

$ archive=/path/to/remote-context.dockercontext
$ file "$archive"
$ tar -tf "$archive"
meta.json
tls

A context produced by the installed Docker client is a POSIX tar archive. A normal listing contains meta.json and may contain a tls entry. The archive is configuration, not an image filesystem, and docker context import is not the same operation as docker image import.

Stop if the path is wrong, the file is not the expected archive, or its provenance is unclear. Do not extract a suspicious archive into your home directory just to inspect it. If the archive includes certificates or keys for a remote daemon, handle it with the same care as any other credential-bearing configuration.

3. Import under a deliberate context name

Choose a name that describes the target, then import the archive:

$ docker context import staging-remote "$archive"
Successfully imported context "staging-remote"
staging-remote

The command creates the named context in the Docker CLI configuration. It does not make that context active. Importing normally needs no sudo: this is a per-user configuration change. Use elevated privileges only if you have intentionally set DOCKER_CONFIG to a directory that your user cannot write, and check the resulting ownership before relying on it.

Docker refuses to replace an existing context with the same name:

$ docker context import staging-remote "$archive"
context "staging-remote" already exists
$ printf '%s\n' "$?"
1

This is a useful guard against an accidental overwrite. Pick a new name, or remove the old context only after inspecting it and confirming that it is no longer needed. Removal is destructive to the local context record and can discard its stored connection material:

$ docker context inspect staging-remote
$ docker context rm staging-remote

Do not run the removal command as part of a trial import. If you removed the wrong context, re-import the original archive with its old name. If that archive is unavailable, restore the Docker configuration from your normal backup rather than guessing at TLS files.

4. Verify the imported endpoint before using it

Inspect the new record and list all contexts:

$ docker context inspect staging-remote
[
    {
        "Name": "staging-remote",
        "Metadata": {
            "Description": "..."
        },
        "Endpoints": {
            "docker": {
                "Host": "unix:///var/run/docker.sock",
                "SkipTLSVerify": false
            }
        }
    }
]
$ docker context ls
NAME             DESCRIPTION       DOCKER ENDPOINT               ERROR
default *                          unix:///var/run/docker.sock
staging-remote                     unix:///var/run/docker.sock

Compare the endpoint with the system you intend to reach. For a remote context, check the host name or socket and confirm that certificate verification is enabled unless you have a documented reason to accept otherwise. An imported context can point to a production daemon; inspection is the point at which you catch a wrong host before issuing a container, image or volume command.

A context can exist even when its daemon is unavailable. The inspect result verifies the stored configuration, not network reachability. If the endpoint should be reachable, test it explicitly without changing the active context:

$ docker --context staging-remote info

Review the output before running commands that change the remote daemon. A connection error means the endpoint, network path, credentials or daemon may need attention; it does not justify disabling TLS verification or changing the imported files blindly.

5. Import from standard input when appropriate

The filename - makes the command read the archive from standard input. This is useful when another trusted transfer step already produces the archive stream:

$ cat "$archive" | docker context import staging-remote-copy -
Successfully imported context "staging-remote-copy"
staging-remote-copy

Prefer a pipeline whose input you can identify and audit. Do not pipe arbitrary network output into Docker, and do not assume that a successful import proves the source was genuine. Verify the resulting context with docker context inspect just as you would for a named file.