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


[API catalog](/reference/api/) · [Docker Engine overview](/reference/api/engine/version/v1.57/) · [Product manual](https://docs.docker.com/engine/) · [OpenAPI specification](/reference/api/engine/version/v1.57.yaml)

API version: 1.57





`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](/reference/api/engine/version/v1.57/#connection)


Server: `/v1.57`

Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement.

```json
null
```

## Example request

Replace placeholders and provide the required credentials or request body.

```console
curl \
  --request PUT \
  --unix-socket "${DOCKER_SOCKET:-/var/run/docker.sock}" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/octet-stream' \
  --data-binary @request-body \
  'http://localhost/v1.57/containers/<ID>/archive?path=%3CPATH%3E'
```


Prepare request-body using the selected media type and schema.


## Parameters

### id

Location: path. Required: yes.

ID or name of the container

```json
{
  "description": "ID or name of the container",
  "in": "path",
  "name": "id",
  "pointer": "/paths/~1containers~1{id}~1archive/put/parameters/0",
  "required": true,
  "schema": {
    "type": "string"
  }
}
```

### path

Location: query. Required: yes.

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

```json
{
  "description": "Path to a directory in the container to extract the archive’s contents into. ",
  "in": "query",
  "name": "path",
  "pointer": "/paths/~1containers~1{id}~1archive/put/parameters/1",
  "required": true,
  "schema": {
    "type": "string"
  }
}
```

### noOverwriteDirNonDir

Location: query. Required: no.

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.


```json
{
  "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",
  "pointer": "/paths/~1containers~1{id}~1archive/put/parameters/2",
  "schema": {
    "type": "string"
  }
}
```

### copyUIDGID

Location: query. Required: no.

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


```json
{
  "description": "If `1`, `true`, then it will copy UID/GID maps to the dest file or\ndir\n",
  "in": "query",
  "name": "copyUIDGID",
  "pointer": "/paths/~1containers~1{id}~1archive/put/parameters/3",
  "schema": {
    "type": "string"
  }
}
```

## Request and responses

### Request  application/octet-stream

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



Schema:

```json
{
  "format": "binary",
  "type": "string"
}
```










### Request  application/x-tar

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



Schema:

```json
{
  "format": "binary",
  "type": "string"
}
```










### Response 200 application/json

The content was extracted successfully











### Response 200 text/plain

The content was extracted successfully











### Response 400 application/json

Bad parameter


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Example:
```json
{
  "message": "not a directory"
}
```


### Response 403 application/json

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


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


### Response 404 application/json

No such container or path does not exist inside the container


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Example:
```json
{
  "message": "No such container: c2ada9df5af8"
}
```


### Response 500 application/json

Server error


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


## Complete operation contract

```json
{
  "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"
  ]
}
```

## Referenced schemas

- [#/components/schemas/ErrorResponse](/reference/api/engine/version/v1.57/schemas/ErrorResponse/)




