> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Download data

> Download files, directories, archives, and signed URLs from persistent volumes.

Download directly from volumes when persistent data needs to leave Nullspace.
Sources are absolute volume-internal paths rooted at `/`.

## Download A File

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  result = volume.files.download_file("/models/model.bin", "./model.bin")
  print(result.path, result.bytes_downloaded)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace volume download team-data /models/model.bin ./model.bin
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # 1. Mint a signed direct download URL for the volume path.
  URL=$(curl -fsS -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/download-url" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/models/model.bin"}' | jq -r .url)

  # 2. Fetch the bytes from the signed URL with GET.
  curl -fsS "${URL}" -o ./model.bin
  ```
</CodeGroup>

Downloads do not overwrite local paths unless you opt in:

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  volume.files.download_file("/models/model.bin", "./model.bin", overwrite=True)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace volume download team-data /models/model.bin ./model.bin --force
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # Overwrite is a client-side concern: the download endpoint is unchanged and
  # `curl -o` simply replaces the local file.
  URL=$(curl -fsS -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/download-url" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/models/model.bin"}' | jq -r .url)
  curl -fsS "${URL}" -o ./model.bin
  ```
</CodeGroup>

CLI `--force` maps to SDK `overwrite=True`.

## Download A Directory

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  volume.files.download_dir("/datasets", "./datasets-copy", overwrite=True)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace volume download team-data /datasets ./datasets-copy --force
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # Directory downloads stream a tar archive: mint a download URL with
  # archive_format=tar, fetch it, then extract locally.
  URL=$(curl -fsS -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/download-url" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/datasets", "archive_format": "tar"}' | jq -r .url)
  curl -fsS "${URL}" -o datasets.tar
  mkdir -p ./datasets-copy && tar -xf datasets.tar -C ./datasets-copy
  ```
</CodeGroup>

Directory downloads fetch a tar archive internally and extract it by default.

## Keep Directory Archives

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  volume.files.download_dir(
      "/datasets",
      "./datasets.tar",
      archive=True,
      overwrite=True,
  )
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace volume download team-data /datasets ./datasets.tar --archive --force --json
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # Keep the tar archive by skipping the local extract step.
  URL=$(curl -fsS -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/download-url" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/datasets", "archive_format": "tar"}' | jq -r .url)
  curl -fsS "${URL}" -o ./datasets.tar
  ```
</CodeGroup>

Use `archive=True` or `--archive` when you want to keep the tar file instead of
extracting it locally.

## Download By Source Type

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
volume.files.download("/models/model.bin", "./model.bin", overwrite=True)
volume.files.download("/datasets", "./datasets-copy", overwrite=True)
```

`download()` checks the source path and dispatches to the file or directory
download helper.

## Signed Download URL

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  file_url = volume.files.download_url("/models/model.bin")
  archive_url = volume.files.download_url("/datasets", archive_format="tar")
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace volume download-url team-data /models/model.bin
  nullspace volume download-url team-data /datasets --archive-format tar
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/download-url" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/models/model.bin"}'

  curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/download-url" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/datasets", "archive_format": "tar"}'
  ```
</CodeGroup>

Use signed URLs when a browser, CI job, or another service should fetch data
directly.

## Related

* [Upload data](./upload-data)
* [File & directory metadata](./file-directory-metadata)
* [CLI volume commands](../cli/manage-volumes)