---
title: How to Upload and Download Files in a MicroVM
description: Copy a single file into or out of a MicroVM&#39;s container using doctl or the API.
product: Microvms
url: https://docs.digitalocean.com/products/microvms/how-to/transfer-files/
last_updated: "2026-11-16"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# How to Upload and Download Files in a MicroVM

DigitalOcean MicroVMs are lightweight virtual machines that run a container image in an isolated kernel, pause automatically when idle, and resume on the next request with memory, files, and processes intact.

You can copy a single file into or out of a DigitalOcean MicroVM’s workload container using `doctl` or the API. Use file transfer to push a configuration file, seed data, or a build artifact into a running MicroVM, or to pull out logs and results, without rebuilding the image.

Each transfer moves one regular file of up to 64 MiB. An upload replaces the file at the destination path atomically, so your application never sees a partly written file. Every transfer reports the file’s SHA-256 checksum so you can confirm the content arrived intact.

If the MicroVM is paused, a transfer resumes it, and billing for compute resumes. If auto-resume is off, [resume the MicroVM](https://docs.digitalocean.com/products/microvms/how-to/pause-resume/index.html.md) first.

## Prerequisites

- An account that is not in a free trial.
- A [personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) with the `microvm:update` scope. Both uploads and downloads need this scope, because a downloaded file can contain secrets.
- For `doctl`, [`doctl`](https://docs.digitalocean.com/reference/doctl/how-to/install/index.html.md) v2.0.1 or later.
- For uploads, the destination’s parent directory must already exist in the container. To create it, [run a command](https://docs.digitalocean.com/products/microvms/how-to/run-commands/index.html.md) such as `mkdir -p /app/config`.

## Transfer Files Using doctl

To upload a file, run `doctl compute microvm upload` with the local file and an absolute destination path in the container:

```shell
doctl compute microvm upload <your-microvm-id> \
  --local-file ./config.json \
  --path /app/config.json
```

The command prints the file’s path, size, SHA-256 checksum, mode, and owner in the container. By default, the file gets mode `0644` and is owned by the container’s user. To change these, add `--mode`, such as `--mode 0600`, or add `--uid` and `--gid` together.

To download a file, run `doctl compute microvm download` with the path in the container and a local path to save to:

```shell
doctl compute microvm download <your-microvm-id> \
  --path /var/log/app.log \
  --save-to ./app.log
```

`doctl` checks the downloaded content against the checksum the MicroVM sends. If the local file already exists, `doctl` overwrites it.

## Transfer Files Using the API

To upload a file, send a `PUT` request to `/v2/microvms/<your-microvm-id>/files` with the destination path in the `path` query parameter and the raw file content as the request body:

```shell
curl -X PUT \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @config.json \
  "https://api.digitalocean.com/v2/microvms/<your-microvm-id>/files?path=/app/config.json"
```

The request must include a `Content-Length` header. `curl` sets it for you with `--data-binary`. The upload accepts the following optional query parameters:

- `mode`: Octal permission bits, from `0001` to `0777`. Defaults to `0644`. Special bits, such as the `setuid`, `setgid`, and sticky bits, are rejected.
- `uid` and `gid`: The file’s owner. Set both or neither. Defaults to the container’s user.
- `sha256`: The lowercase hex SHA-256 of the body. If the content does not match, the upload fails and the existing file is left unchanged.

A successful upload returns HTTP 200 with the file’s `path`, `size_bytes`, `sha256`, `mode`, `uid`, and `gid`. The `X-Checksum-Sha256` response header repeats the checksum.

To download a file, send a `GET` request to the same endpoint:

```shell
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -o app.log \
  -D - \
  "https://api.digitalocean.com/v2/microvms/<your-microvm-id>/files?path=/var/log/app.log"
```

The response body is the raw file content. The `X-Checksum-Sha256` response header contains the file’s SHA-256 checksum. Compare it with the checksum of the file you saved, for example with `sha256sum app.log`.

## Errors

Both directions return the following errors:

| Status | Meaning |
|---|---|
| 400 | The path is missing, relative, or not clean, such as a path containing `..` or a trailing `/`. A query parameter is malformed, or the upload body ended early. Also returned while the MicroVM is provisioning. |
| 403 | The token does not have the `microvm:update` scope, file transfer is not available for your team, or the container user cannot read or write the file. |
| 404 | The MicroVM does not exist, or the file or its parent directory does not exist in the container. |
| 409 | The workload is not running, the path is a directory or another file type that is not a regular file, or the MicroVM is too old to support file transfer. To use file transfer on an older MicroVM, create a new MicroVM. |
| 411 | The upload has no `Content-Length` header. |
| 413 | The file is larger than 64 MiB, or the container’s disk is full. |
| 422 | The uploaded content does not match the `sha256` you sent. |
| 429 | The MicroVM is already serving four downloads, or the service is busy. Retry after a short delay. |
| 504 | The transfer did not finish within 10 minutes. |

An upload does not follow or replace a symbolic link at the destination path. Upload to the file the link points to instead.

To move a whole directory, archive it first, then transfer the archive. For example, run `tar czf /tmp/data.tgz /app/data` with `doctl compute microvm exec`, then download `/tmp/data.tgz`.

For other limits, see [MicroVMs Limits](https://docs.digitalocean.com/products/microvms/details/limits/index.html.md#file-transfer-limits).