Search or ask Docker

Create an image

POST /images/create — Docker Engine API 1.57.

View Markdown
POST/images/create
Pull or import an image.

Connection and access

API connection and authentication guidance

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

/v1.57

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

Parameters

fromImage query

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.

Type: string

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

fromSrc query

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.

Type: string

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

repo query

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.

Type: string

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

tag query

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

Type: string

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

message query

Set commit message for imported image.

Type: string

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

X-Registry-Auth header

A base64url-encoded auth configuration.

Refer to the authentication section for details.

Type: string

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

changes query

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

Type: array

Array item

Type: string

All schema constraints and annotations
{
  "type": "string"
}
All schema constraints and annotations
{
  "items": {
    "type": "string"
  },
  "type": "array"
}

Serialization: form

platform query

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.

Type: string

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

Request and responses

Request

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

application/octet-stream

Type: string

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

Request

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

text/plain

Type: string

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

Response 200

no error

application/json

Response 404

repository does not exist or no read access

application/json

Schema: ErrorResponse

Schema example

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

Response 500

server error

application/json

Schema: ErrorResponse

Schema example

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

Referenced schemas

#/components/schemas/ErrorResponse

Complete operation contract
{
  "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"
  ]
}