# Create an image


[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





`POST /images/create`

Pull or import an image.

## Connection and access

[API connection and authentication guidance](/reference/api/engine/version/v1.57/#connection)

`X-Registry-Auth` delegates registry credentials and does not authenticate the daemon caller.


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 POST \
  --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/images/create'
```


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


## Parameters

### fromImage

Location: query. Required: no.

Name of the image to pull. If the name includes a tag or digest, specific behavior applies:

- If only `fromImage` includes a tag, that tag is used.
- If both `fromImage` and `tag` are provided, `tag` takes precedence.
- If `fromImage` includes a digest, the image is pulled by digest, and `tag` is ignored.
- If neither a tag nor digest is specified, all tags are pulled.


```json
{
  "description": "Name of the image to pull. If the name includes a tag or digest, specific behavior applies:\n\n- If only `fromImage` includes a tag, that tag is used.\n- If both `fromImage` and `tag` are provided, `tag` takes precedence.\n- If `fromImage` includes a digest, the image is pulled by digest, and `tag` is ignored.\n- If neither a tag nor digest is specified, all tags are pulled.\n",
  "in": "query",
  "name": "fromImage",
  "pointer": "/paths/~1images~1create/post/parameters/0",
  "schema": {
    "type": "string"
  }
}
```

### fromSrc

Location: query. Required: no.

Source to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.

```json
{
  "description": "Source to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.",
  "in": "query",
  "name": "fromSrc",
  "pointer": "/paths/~1images~1create/post/parameters/1",
  "schema": {
    "type": "string"
  }
}
```

### repo

Location: query. Required: no.

Repository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.

```json
{
  "description": "Repository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.",
  "in": "query",
  "name": "repo",
  "pointer": "/paths/~1images~1create/post/parameters/2",
  "schema": {
    "type": "string"
  }
}
```

### tag

Location: query. Required: no.

Tag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.

```json
{
  "description": "Tag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.",
  "in": "query",
  "name": "tag",
  "pointer": "/paths/~1images~1create/post/parameters/3",
  "schema": {
    "type": "string"
  }
}
```

### message

Location: query. Required: no.

Set commit message for imported image.

```json
{
  "description": "Set commit message for imported image.",
  "in": "query",
  "name": "message",
  "pointer": "/paths/~1images~1create/post/parameters/4",
  "schema": {
    "type": "string"
  }
}
```

### X-Registry-Auth

Location: header. Required: no.

A base64url-encoded auth configuration.

Refer to the [authentication section](/reference/api/engine/version/v1.57/#authentication) for
details.


```json
{
  "description": "A base64url-encoded auth configuration.\n\nRefer to the [authentication section](#section/Authentication) for\ndetails.\n",
  "in": "header",
  "name": "X-Registry-Auth",
  "pointer": "/paths/~1images~1create/post/parameters/5",
  "schema": {
    "type": "string"
  }
}
```

### changes

Location: query. Required: no.

Apply `Dockerfile` instructions to the image that is created,
for example: `changes=ENV DEBUG=true`.
Note that `ENV DEBUG=true` should be URI component encoded.
Repeat the parameter to apply multiple instructions.

Supported `Dockerfile` instructions:
`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`


```json
{
  "description": "Apply `Dockerfile` instructions to the image that is created,\nfor example: `changes=ENV DEBUG=true`.\nNote that `ENV DEBUG=true` should be URI component encoded.\nRepeat the parameter to apply multiple instructions.\n\nSupported `Dockerfile` instructions:\n`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`\n",
  "explode": true,
  "in": "query",
  "name": "changes",
  "pointer": "/paths/~1images~1create/post/parameters/6",
  "schema": {
    "items": {
      "type": "string"
    },
    "type": "array"
  },
  "style": "form"
}
```

### platform

Location: query. Required: no.

Platform in the format os[/arch[/variant]].

When used in combination with the `fromImage` option, the daemon checks
if the given image is present in the local image cache with the given
OS and Architecture, and otherwise attempts to pull the image. If the
option is not set, the host's native OS and Architecture are used.
If the given image does not exist in the local image cache, the daemon
attempts to pull the image with the host's native OS and Architecture.
If the given image does exists in the local image cache, but its OS or
architecture does not match, a warning is produced.

When used with the `fromSrc` option to import an image from an archive,
this option sets the platform information for the imported image. If
the option is not set, the host's native OS and Architecture are used
for the imported image.


```json
{
  "description": "Platform in the format os[/arch[/variant]].\n\nWhen used in combination with the `fromImage` option, the daemon checks\nif the given image is present in the local image cache with the given\nOS and Architecture, and otherwise attempts to pull the image. If the\noption is not set, the host's native OS and Architecture are used.\nIf the given image does not exist in the local image cache, the daemon\nattempts to pull the image with the host's native OS and Architecture.\nIf the given image does exists in the local image cache, but its OS or\narchitecture does not match, a warning is produced.\n\nWhen used with the `fromSrc` option to import an image from an archive,\nthis option sets the platform information for the imported image. If\nthe option is not set, the host's native OS and Architecture are used\nfor the imported image.\n",
  "in": "query",
  "name": "platform",
  "pointer": "/paths/~1images~1create/post/parameters/7",
  "schema": {
    "default": "",
    "type": "string"
  }
}
```

## Request and responses

### Request  application/octet-stream

Image content if the value `-` has been specified in fromSrc query parameter


Schema:

```json
{
  "type": "string"
}
```










### Request  text/plain

Image content if the value `-` has been specified in fromSrc query parameter


Schema:

```json
{
  "type": "string"
}
```










### Response 200 application/json

no error











### Response 404 application/json

repository does not exist or no read access


Schema:

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









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


### Response 500 application/json

server error


Schema:

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









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


## Complete operation contract

```json
{
  "description": "Pull or import an image.",
  "operationId": "ImageCreate",
  "parameters": [
    {
      "description": "Name of the image to pull. If the name includes a tag or digest, specific behavior applies:\n\n- If only `fromImage` includes a tag, that tag is used.\n- If both `fromImage` and `tag` are provided, `tag` takes precedence.\n- If `fromImage` includes a digest, the image is pulled by digest, and `tag` is ignored.\n- If neither a tag nor digest is specified, all tags are pulled.\n",
      "in": "query",
      "name": "fromImage",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Source to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.",
      "in": "query",
      "name": "fromSrc",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Repository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.",
      "in": "query",
      "name": "repo",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Tag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.",
      "in": "query",
      "name": "tag",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Set commit message for imported image.",
      "in": "query",
      "name": "message",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "A base64url-encoded auth configuration.\n\nRefer to the [authentication section](#section/Authentication) for\ndetails.\n",
      "in": "header",
      "name": "X-Registry-Auth",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Apply `Dockerfile` instructions to the image that is created,\nfor example: `changes=ENV DEBUG=true`.\nNote that `ENV DEBUG=true` should be URI component encoded.\nRepeat the parameter to apply multiple instructions.\n\nSupported `Dockerfile` instructions:\n`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`\n",
      "explode": true,
      "in": "query",
      "name": "changes",
      "schema": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "style": "form"
    },
    {
      "description": "Platform in the format os[/arch[/variant]].\n\nWhen used in combination with the `fromImage` option, the daemon checks\nif the given image is present in the local image cache with the given\nOS and Architecture, and otherwise attempts to pull the image. If the\noption is not set, the host's native OS and Architecture are used.\nIf the given image does not exist in the local image cache, the daemon\nattempts to pull the image with the host's native OS and Architecture.\nIf the given image does exists in the local image cache, but its OS or\narchitecture does not match, a warning is produced.\n\nWhen used with the `fromSrc` option to import an image from an archive,\nthis option sets the platform information for the imported image. If\nthe option is not set, the host's native OS and Architecture are used\nfor the imported image.\n",
      "in": "query",
      "name": "platform",
      "schema": {
        "default": "",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/octet-stream": {
        "schema": {
          "type": "string"
        }
      },
      "text/plain": {
        "schema": {
          "type": "string"
        }
      }
    },
    "description": "Image content if the value `-` has been specified in fromSrc query parameter",
    "required": false,
    "x-codegen-request-body-name": "inputImage"
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {}
      },
      "description": "no error"
    },
    "404": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "repository does not exist or no read access"
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "server error"
    }
  },
  "summary": "Create an image",
  "tags": [
    "Image"
  ]
}
```

## Referenced schemas

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




