MicroDuck Local Training: Setup, Checks & First Run

1. Create a separate, versioned environment.

Use a machine with a compatible NVIDIA driver and CUDA-capable GPU. If you are choosing a computer, first read the environment comparison. Install Git and uv from its official instructions ↗. Run the following from a parent directory where microduck-rl-first-run does not already exist.

git clone https://github.com/pollen-robotics/microduck_rl.git microduck-rl-first-run
cd microduck-rl-first-run
git checkout --detach 2b25a48b08f1f17bc38c90bb03144c81fbd9ed07
uv python install 3.12
uv sync --locked --python 3.12

The reviewed project permits Python 3.12 and excludes 3.13. The detached checkout keeps this walkthrough on one revision; it does not update an existing project. --locked requires the lockfile to agree with the project instead of silently resolving a new dependency set. If it reports a mismatch, save the error rather than deleting the lockfile. Sources: Python, dependency pins and ARM package sources ↗, uv: installing a specific Python version ↗ and uv: locking and syncing a project ↗.

2. Check the environment that will run training.

uv run python - <<'PY'
import platform
import torch
print("Python:", platform.python_version())
print("Machine:", platform.system(), platform.machine())
print("PyTorch:", torch.__version__)
print("Built for CUDA:", torch.version.cuda)
print("CUDA available:", torch.cuda.is_available())
print("GPU count:", torch.cuda.device_count())
if torch.cuda.is_available():
    print("GPU:", torch.cuda.get_device_name(0))
PY

For this CUDA route, expect Python 3.12.x, a CUDA build of PyTorch, CUDA available: True and at least one visible GPU. This checks discovery, not memory capacity or complete training compatibility. If importing PyTorch itself fails, keep that traceback and use the dependency troubleshooting guide. PyTorch: checking CUDA availability ↗ explains the availability check.

uv run list-envs

Find Mjlab-Velocity-Flat-MicroDuck in the output before using it below. If it is missing, verify the checkout and installed project rather than copying a task name from another fork. MicroDuck RL quick start and task registry ↗.

3. Run a brief installation check.

uv run train Mjlab-Velocity-Flat-MicroDuck \
  --env.scene.num-envs 64 \
  --agent.max_iterations 5

This starts real local GPU work. We chose 64 environments and 5 iterations to keep the check bounded; they are not a published hardware minimum. A useful pass is the task initializing and iteration logs advancing without an exception. If the run stops for an account or logging prompt, complete the requested setup and repeat the same check. If it fails, record the first error and the last successful stage.

Once the small run works, plan a longer run around your GPU memory and time budget. Increasing parallel environments or iterations changes the experiment; record those choices. A policy trained for five iterations is not expected to walk well.

4. Keep the checkpoint and its context.

Save the actual checkpoint path or W&B run path printed by your run, together with the task ID and configuration. A .pt training checkpoint is an input to the exporter; changing its extension does not turn it into a deployable model. Continue with the ONNX export and replay guide.

Date and goal:
Repository URL and full commit:
Uncommitted changes:
OS / architecture / Python / uv:
GPU / driver / PyTorch / CUDA build:
Task ID:
Exact command:
Environment count / iteration limit / seed:
Run URL and checkpoint path:
What initialized successfully:
Observed result or first error:
One change for the next attempt:

5. Preview a cloud route if local compute is unsuitable.

In a configured checkout, the official wrapper can prepare a job specification without submitting a GPU job. Authentication setup is documented in MicroDuck cloud job submission guide ↗. The following uses a one-hour cap as an example, not a promised completion time.

uv run train Mjlab-Velocity-Flat-MicroDuck \
  --env.scene.num-envs 64 \
  --agent.max_iterations 5 \
  --hf-jobs --timeout 1h --dry-run

The preview prepares a local source archive and prints the job specification. Inspect the hardware, namespace and source files; remove local secrets from anything that would be uploaded. Only removing --dry-run starts the submission path. A Mac may still encounter dependency or import problems before reaching this wrapper; a cloud destination does not bypass the local launcher’s requirements. Cloud submission and checkpoint export implementation ↗.

Before submitting, read Hugging Face Jobs: current pricing and billing ↗. After submission, keep the job URL. Ctrl-C detaches the MicroDuck log stream; it does not cancel the remote job. Cancel from the job page or follow Hugging Face: managing and cancelling jobs ↗, and verify its stopped state.

Continue with your result.