# Download Files

`dl.download` is one function that handles four cases. It looks at the kind of the resolved node and picks the right strategy.

## A single file by path

Inside a `Prefix` context:

```python
import dreamlake as dl

with dl.Prefix(project="robotics@alice", prefix="/session-100"):
    dl.download("camera/front/clip.mp4", to="./out/")
```

Or with an absolute path, no context needed:

```python
dl.download(
    "/session-100/camera/front/clip.mp4",
    project="robotics@alice",
    to="./out/clip.mp4",
)
```

If `to=` ends with a `/` or is an existing directory, the file lands inside it with its original filename. Otherwise `to=` is the exact output path.

## A whole folder, recursive

Pass a folder path — `dl.download` recognizes the kind is `folder` (not a file) and streams every descendant leaf, preserving relative paths:

```python
with dl.Prefix(project="robotics@alice", prefix="/session-100"):
    dl.download("camera", to="./camera-dl/")
```

Result:

```
./camera-dl/
├── front/clip.mp4
└── rear/clip.mp4
```

## An entire episode

Same function, pass the episode path:

```python
dl.download("/session-100", project="robotics@alice", to="./session-100-dl/")
```

Every file across every sub-folder of the episode is downloaded with its full structure under `to=`.

## By node ID

If you already have an ID (from a previous `dl.upload` response, a `lookup_node` call, or the preview UI), pass it directly. The SDK detects a 24-char hex string and skips path resolution:

```python
dl.download("69e7264a1234567890abcdef", to="./out/")
```

Works for any kind — files, folders, episodes.

## A whole bindr

Bindrs need a separate function because they can mix files and folders from anywhere:

```python
dl.download_bindr(
    "training-set",
    project="robotics@alice",
    to="./train/",
)
```

Each member becomes a top-level entry under `to=`. Folder members keep their internal structure; file members land directly.

## Best practices

- **Pick `to=` for the unit you're pulling.** A single file → use a filename or directory. A folder → use a directory. The SDK creates `to=` if it doesn't exist.
- **Don't pre-flatten with absolute paths in your code.** Let the SDK rebuild the tree under `to=` — that way the output mirrors what's in DreamLake.
- **Bytes flow direct from S3.** The download URL is presigned and short-lived; the bytes never traverse the BSS server. This means big files don't compete for server bandwidth.
- **Resume isn't built into the high-level API yet.** If a multi-gigabyte folder download is interrupted, re-run — already-downloaded files are overwritten cheaply, but partial files restart from zero.

## What you can do next

- [Bindrs](/examples-bindrs.md) — curate exactly what you want to download
- [Upload an Episode](/examples-upload-episode.md) — get data in so you have something to pull back
