Search or ask Docker

Extract an archive of files or folders to a directory in a container

PUT /containers/{id}/archive — Docker Engine API 1.57.

View Markdown
PUT/containers/{id}/archive
Upload a tar archive to be extracted to a path in the filesystem of container id. path parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

Connection and access

API connection and authentication guidance

/v1.57

No HTTP authentication requirement is declared for this operation. Transport access controls can still apply.

Parameters

id path Required

ID or name of the container

Type: string

All schema constraints and annotations
{
  "type": "string"
}

path query Required

Path to a directory in the container to extract the archive’s contents into.

Type: string

All schema constraints and annotations
{
  "type": "string"
}

noOverwriteDirNonDir query

If 1, true, or True then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa.

Type: string

All schema constraints and annotations
{
  "type": "string"
}

copyUIDGID query

If 1, true, then it will copy UID/GID maps to the dest file or dir

Type: string

All schema constraints and annotations
{
  "type": "string"
}

Request and responses

Request

The input stream must be a tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, or xz.

application/octet-stream

Type: string

All schema constraints and annotations
{
  "format": "binary",
  "type": "string"
}

Request

The input stream must be a tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, or xz.

application/x-tar

Type: string

All schema constraints and annotations
{
  "format": "binary",
  "type": "string"
}

Response 200

The content was extracted successfully

application/json

Response 200

The content was extracted successfully

text/plain

Response 400

Bad parameter

application/json

Schema: ErrorResponse

Example

{
  "message": "not a directory"
}

Response 403

Permission denied, the volume or container rootfs is marked as read-only.

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Response 404

No such container or path does not exist inside the container

application/json

Schema: ErrorResponse

Example

{
  "message": "No such container: c2ada9df5af8"
}

Response 500

Server error

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Referenced schemas

#/components/schemas/ErrorResponse

Complete operation contract
{
  "description": "Upload a tar archive to be extracted to a path in the filesystem of container id.\n`path` parameter is asserted to be a directory. If it exists as a file, 400 error\nwill be returned with message \"not a directory\".\n",
  "operationId": "PutContainerArchive",
  "parameters": [
    {
      "description": "ID or name of the container",
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Path to a directory in the container to extract the archive’s contents into. ",
      "in": "query",
      "name": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "If `1`, `true`, or `True` then it will be an error if unpacking the\ngiven content would cause an existing directory to be replaced with\na non-directory and vice versa.\n",
      "in": "query",
      "name": "noOverwriteDirNonDir",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "If `1`, `true`, then it will copy UID/GID maps to the dest file or\ndir\n",
      "in": "query",
      "name": "copyUIDGID",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/octet-stream": {
        "schema": {
          "format": "binary",
          "type": "string"
        }
      },
      "application/x-tar": {
        "schema": {
          "format": "binary",
          "type": "string"
        }
      }
    },
    "description": "The input stream must be a tar archive compressed with one of the\nfollowing algorithms: `identity` (no compression), `gzip`, `bzip2`,\nor `xz`.\n",
    "required": true,
    "x-codegen-request-body-name": "inputStream"
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {},
        "text/plain": {}
      },
      "description": "The content was extracted successfully"
    },
    "400": {
      "content": {
        "application/json": {
          "example": {
            "message": "not a directory"
          },
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "Bad parameter"
    },
    "403": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "Permission denied, the volume or container rootfs is marked as read-only."
    },
    "404": {
      "content": {
        "application/json": {
          "example": {
            "message": "No such container: c2ada9df5af8"
          },
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "No such container or path does not exist inside the container"
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "Server error"
    }
  },
  "summary": "Extract an archive of files or folders to a directory in a container",
  "tags": [
    "Container"
  ]
}