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

# Train a YOLO object detector

> Train YOLO26n on an L4, keep the checkpoint in a volume, and predict from a second function.

The `yolo-artifacts` volume also keeps metrics and annotated images after both
containers exit.

The default run trains on Ultralytics' eight-image COCO8 dataset for one
epoch. Use it to check training, checkpoint storage, and prediction before
spending GPU time on your own dataset.

`app.py` in the downloaded project defines both functions and their resources.

The CLI installs once with `uv tool install lazycloud-client`. The commands
below download a standalone project and install its dependencies, with no
repository checkout. The rest of the guide runs from that directory through
`uv run`, which uses the project's pinned SDK.

```bash theme={null}
lazycloud example download yolo-training
cd yolo-training
uv sync
uv run lazycloud login
```

You need access to an L4 and a positive credit balance. Training and prediction
both use GPU compute. Check [Ultralytics licensing](https://www.ultralytics.com/license)
before adapting the example for commercial use.

## Define shared storage

Both functions use the pinned Ultralytics image in `app.py`. Training writes a
checkpoint and metrics, and prediction reads that checkpoint from the same
volume. The code rejects paths outside the volume and refuses to overwrite an
existing run directory.

```python theme={null}
from lazycloud import Volume

artifact_volume = Volume("yolo-artifacts", "/artifacts")
```

Both decorators include `volumes=[artifact_volume]`. The first invocation
creates the volume if it does not exist, and later calls reuse it. Importing
the module creates no remote resources.

Torch, CUDA, and Ultralytics stay inside the image. Nothing installs on your
machine.

## Train

With no arguments, the function uses `coco8.yaml`, YOLO26n, and one epoch:

```bash theme={null}
uv run lazycloud run app:train_yolo
```

The command shows training logs and returns checkpoint and metrics paths.
Download the metrics CSV:

```bash theme={null}
uv run lazycloud cp lazycloud://yolo-artifacts/training/coco8-smoke/results.csv ./results.csv
```

LazyCloud charges compute while the container runs, including startup and its
idle window. For this one-epoch run, startup and the model download often take
longer than training. Check the Usage page before raising `epochs`, image size,
or dataset size.

## Predict

The prediction function loads the saved `best.pt` and runs it on Ultralytics'
public `bus.jpg` by default:

```bash theme={null}
uv run lazycloud run app:predict_yolo
uv run lazycloud cp lazycloud://yolo-artifacts/predictions/bus-prediction/bus.jpg ./bus-prediction.jpg
```

Open `bus-prediction.jpg` to see the detected objects. A one-epoch run only
checks the workflow. Evaluate accuracy on your own data before using the
predictions in a product.

## Use your own data

Upload the dataset and its Ultralytics YAML to the volume. Paths inside the
YAML must also point at files under `/artifacts`.

Create the volume and upload from Python. This works even if you have not run
the sample:

```python theme={null}
from app import artifact_volume

artifact_volume.create()
artifact_volume.put("datasets/my-detector", "datasets/my-detector")
```

`create()` reuses an existing volume. After the upload, train on your data:

```bash theme={null}
uv run lazycloud run app:train_yolo custom-run 50 datasets/my-detector/data.yaml
```

To predict on an uploaded image, pass its volume-relative path as the third
argument. The first two name the training run and the prediction run:

```bash theme={null}
uv run lazycloud cp ./sample.jpg lazycloud://yolo-artifacts/inputs/sample.jpg
uv run lazycloud run app:predict_yolo custom-run sample-prediction inputs/sample.jpg
```

A run name works only once, so earlier checkpoints stay intact. Give each new
trial a new training name and pass that name to prediction.

If training fails, find the task with `uv run lazycloud task list --app yolo_training`
and read its logs. Check the dataset path before retrying with a new name.

## Clean up

The function containers shut down after their idle window. Keep the volume
while you still need the checkpoints, and download the files you want before
deleting anything.

Remove runs you no longer need:

```bash theme={null}
uv run lazycloud rm yolo-artifacts/training/coco8-smoke
uv run lazycloud rm yolo-artifacts/predictions/bus-prediction
```

Or delete the whole volume:

```bash theme={null}
uv run lazycloud volume delete yolo-artifacts
```

<Warning>
  Deleting the volume deletes every checkpoint in it. Download what you want
  to keep first.
</Warning>

## Licenses

* The image is Ultralytics `8.4.101` and the model is `yolo26n.pt`. Read the
  [Ultralytics licensing options](https://www.ultralytics.com/license) before
  distributing a model or using one commercially.
* [COCO8](https://docs.ultralytics.com/datasets/detect/coco8/) is the first
  eight COCO 2017 images and labels. Check COCO's terms and each image's
  license before reusing them outside this test.
* Your own data is your responsibility: collection rights, annotation
  license, privacy, and permitted model use.