Give Feedback

pydo.images.create_custom()

Generated on 17 Jun 2026 from pydo version v0.37.0

Copy page as Markdown View page as Markdown

Usage

client.images.create_custom(
    body={
        "name": "Nifty New Snapshot",
        "distribution": "Ubuntu",
        "description": " ",
        ...,
    },
)

Returns JSONRaises HttpResponseError

Description

To create a new custom image, send a POST request to /v2/images. The body must contain a url attribute pointing to a Linux virtual machine image to be imported into DigitalOcean. The image must be in the raw, qcow2, vhdx, vdi, or vmdk format. It may be compressed using gzip or bzip2 and must be smaller than 100 GB after being decompressed.

Parameters

name string required

Example: Nifty New Snapshot

The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question.

distribution string optional

The name of a custom image's distribution. Currently, the valid values are Arch Linux, CentOS, CoreOS, Debian, Fedora, Fedora Atomic, FreeBSD, Gentoo, openSUSE, RancherOS, Rocky Linux, Ubuntu, and Unknown. Any other value will be accepted but ignored, and Unknown will be used in its place.

One of: Arch Linux, CentOS, CoreOS, Debian, Fedora, Fedora Atomic, FreeBSD, Gentoo, openSUSE, RancherOS, Rocky Linux, Ubuntu, Unknown

description string optional

An optional free-form text field to describe an image.

url string required

Example: http://cloud-images.ubuntu.com/minimal/releases/bionic/release/ubuntu-18.04-minimal-cloudimg-amd64.img

A URL from which the custom Linux virtual machine image may be retrieved. The image it points to must be in the raw, qcow2, vhdx, vdi, or vmdk format. It may be compressed using gzip or bzip2 and must be smaller than 100 GB after being decompressed.

region string required

The slug identifier for the region where the resource will initially be available.

One of: ams1, ams2, ams3, blr1, fra1, lon1, nyc1, nyc2, nyc3, sfo1, sfo2, sfo3, sgp1, tor1, syd1

tags array of strings or null optional

Example: ['base-image', 'prod']

A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags.

Requires tag:create scope.

Request Sample

Show Request Sample

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "name": "ubuntu-18.04-minimal",
  "url": "http://cloud-images.ubuntu.com/minimal/releases/bionic/release/ubuntu-18.04-minimal-cloudimg-amd64.img",
  "distribution": "Ubuntu",
  "region": "nyc3",
  "description": "Cloud-optimized image w/ small footprint",
  "tags": [
    "base-image",
    "prod"
  ]
}

resp = client.images.create_custom(body=req)

Response Example

Show Response Example

{
  "image": {
    "created_at": "2018-09-20T19:28:00Z",
    "description": "Cloud-optimized image w/ small footprint",
    "distribution": "Ubuntu",
    "error_message": "",
    "id": 38413969,
    "name": "ubuntu-18.04-minimal",
    "regions": [],
    "type": "custom",
    "tags": [
      "base-image",
      "prod"
    ],
    "status": "NEW"
  }
}

More Information

See /v2/images in the API reference for additional detail on responses, headers, parameters, and more.