Search or ask Docker

Push an image

POST /images/{name}/push — Docker Engine API 1.57.

View Markdown
POST/images/{name}/push

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, registry.example.com/myimage:latest.

The push is cancelled if the HTTP connection is closed.

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

name path Required

Name of the image to push. For example, registry.example.com/myimage. The image must be present in the local image store with the same name.

The name should be provided without tag; if a tag is provided, it is ignored. For example, registry.example.com/myimage:latest is considered equivalent to registry.example.com/myimage.

Use the tag parameter to specify the tag to push.

Type: string

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

tag query

Tag of the image to push. For example, latest. If no tag is provided, all tags of the given image that are present in the local image store are pushed.

Type: string

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

platform query

JSON-encoded OCI platform to select the platform-variant to push. If not provided, all available variants will attempt to be pushed.

If the daemon provides a multi-platform image store, this selects the platform-variant to push to the registry. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.

Example: {"os": "linux", "architecture": "arm", "variant": "v5"}

Type: string

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

X-Registry-Auth header Required

A base64url-encoded auth configuration.

Refer to the authentication section for details.

Type: string

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

Request and responses

Response 200

No error

application/json

Response 200

No error

text/plain

Response 404

No such image

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": "Push an image to a registry.\n\nIf you wish to push an image on to a private registry, that image must\nalready have a tag which references the registry. For example,\n`registry.example.com/myimage:latest`.\n\nThe push is cancelled if the HTTP connection is closed.\n",
  "operationId": "ImagePush",
  "parameters": [
    {
      "description": "Name of the image to push. For example, `registry.example.com/myimage`.\nThe image must be present in the local image store with the same name.\n\nThe name should be provided without tag; if a tag is provided, it\nis ignored. For example, `registry.example.com/myimage:latest` is\nconsidered equivalent to `registry.example.com/myimage`.\n\nUse the `tag` parameter to specify the tag to push.\n",
      "in": "path",
      "name": "name",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Tag of the image to push. For example, `latest`. If no tag is provided,\nall tags of the given image that are present in the local image store\nare pushed.\n",
      "in": "query",
      "name": "tag",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "JSON-encoded OCI platform to select the platform-variant to push.\nIf not provided, all available variants will attempt to be pushed.\n\nIf the daemon provides a multi-platform image store, this selects\nthe platform-variant to push to the registry. If the image is\na single-platform image, or if the multi-platform image does not\nprovide a variant matching the given platform, an error is returned.\n\nExample: `{\"os\": \"linux\", \"architecture\": \"arm\", \"variant\": \"v5\"}`\n",
      "in": "query",
      "name": "platform",
      "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",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {},
        "text/plain": {}
      },
      "description": "No error"
    },
    "404": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "No such image"
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "Server error"
    }
  },
  "summary": "Push an image",
  "tags": [
    "Image"
  ],
  "x-consumes": [
    "application/octet-stream"
  ]
}