How to Upload Custom Images

Validated on 25 Aug 2020 • Last edited on 8 Feb 2024 disk image

Custom images are Linux and Unix-like images you import to DigitalOcean. You can create Droplets based custom images, which lets you migrate and scale your workloads without spending time recreating your environment from scratch.

Image Requirements

Images you upload to DigitalOcean must meet the following requirements:

  • Operating system. Images must have a Unix-like OS.

  • File format. Images must be in one of the following file formats:

  • Size. Images must be 100 GB or less when uncompressed, including the filesystem.

  • Filesystem. Images must support the ext3 or ext4 filesystems.

  • cloud-init. Images must have cloud-init 0.7.7 or higher, cloudbase-init, coreos-cloudinit, ignition, or bsd-cloudinit installed and configured correctly. If your image’s default cloud-init configuration lists the NoCloud data source before the ConfigDrive data source, Droplets created from your image will not function properly.

    Click here to display detailed cloud-init instructions.

    If your image’s default cloud-init configuration lists the NoCloud data source before the ConfigDrive data source, Droplets created from your image will not function properly. We have detailed instructions on reconfiguring cloud-init for Ubuntu 18.04.

    The process for fixing this in general is to edit the cloud-init config file either using a text editor or with dpkg-reconfigure to order the data sources correctly. The actual line in the file should look similar to this when you’re done:

    data source_list: [ ConfigDrive, OpenNebula, DigitalOcean, Azure, AltCloud, OVF, MAAS, GCE, OpenStack, CloudSigma, SmartOS, None, NoCloud ]

    After you edit the file, you need to purge the previous cloud-init data so cloud-init runs using the proper data source when your Droplet boots. You can do this using cloud-init clean or by manually cleaning out /var/lib/cloud. You should also verify the networking configuration, the details of which vary by distribution.

  • SSH configuration. Images must have sshd installed and configured to run on boot. If your image does not have sshd set up, you will not have SSH access to Droplets created from that image unless you recover access using the Recovery Console.

You can also upload a custom image that meets the above criteria as a compressed gzip or bzip2 file.

Warning
You must add an SSH key when creating Droplets from a custom image. These Droplets have password authentication disabled by default and you cannot use the control panel to reset the root password.

You can find cloud-friendly official Unix-like OS images on OpenStack.

Upload a Custom Image using Automation

How to upload a custom image using the DigitalOcean CLI

To upload a custom image via the command-line, follow these steps:

  1. Install doctl, the DigitalOcean command-line tool.

  2. Create a personal access token, and save it for use with doctl.

  3. Use the token to grant doctl access to your DigitalOcean account.

                  doctl auth init

  4. Finally, upload a custom image with doctl compute image create. The basic usage looks like this, but you'll want to read the usage docs for more details:

                  doctl compute image create <image-name> [flags]

    The following example creates a custom image named Example Image from a URL and stores it in the nyc1 region

                   doctl compute image create "Example Image" --image-url "https
How to upload a custom image using the DigitalOcean API

To upload a custom image using the DigitalOcean API, follow these steps:

  1. Create a personal access token, and save it for use with the API.

  2. Send a POST request to https://api.digitalocean.com/v2/images

    cURL

    To upload a custom image with cURL, call:

    
                curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"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"]}' \
  "https://api.digitalocean.com/v2/images"

    Python

    
                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)

Upload a Custom Image using the Control Panel

To upload an image via the control panel, click Images in the main navigation, then click the Custom Images tab.

Custom Images tab in the control panel

Here, you can upload a custom image in two ways:

  • You can upload an image file directly by clicking the Upload Image button, which opens a file selector, or by dragging and dropping the image file into the window.

    Note
    Some browsers have file size limitations. If you’re unable to upload a large file via your browser, you can host the file somewhere and upload it by URL. For example, you can upload your image to Spaces and make the file public or use a file sharing tool like Dropbox. Make sure the URL ends in the file extension (like example.com/file.raw instead of example.com/file.raw?dl=0).

  • You can enter the URL to an image file by clicking the Import via URL button. In the Upload an Image window that opens, enter the URL of the image you want to use in the text field, then click Next. The control panel supports uploads from HTTP, HTTPS, and FTP URLs.

    Note
    Importing a custom image by URL will fail if the image is served by a CDN that doesn’t support HEAD requests. If you have trouble importing an image via a URL, try downloading the file and uploading it directly.

Using either upload method, the next window that opens prompts you to enter details about your image.

Upload an image window

  • Edit Image Name: This field is pre-filled with the name of the file you uploaded, but you can customize it if you like.

  • Distribution: You can choose from Arch Linux, Fedora, Ubuntu, CentOS, Debian, or Unknown.

  • Choose a datacenter region: Your image is located in a single datacenter of your choice at first, and you can transfer custom images to different datacenters after uploading.

  • Tags (optional): Custom images support tagging. You can add tags to your custom image here or at any time after uploading.

  • Notes (optional): This is a plain text field you can use to enter any additional notes about your custom image for your use.

After you’ve entered these details, click Upload Image. A progress bar appears on the control panel next to the Upload Image button. If you click on Details above this progress bar, a window appears listing all of your current uploads.

Custom image upload progress window

You can click the X next to any in-progress upload to cancel it, or click Cancel Uploads to cancel all current uploads.

Once you have at least one custom image added to your account, you can create a Droplet from a custom image.

Control Panel Blog Pricing Careers Terms Privacy Status API Docs Tutorials Support