donkey train

The donkey train command trains a neural network model using data collected from manual driving sessions. The trained model can then be used for autonomous driving.

Usage

donkey train [options]

Options

--tub

string[]

required

Path(s) to tub directories containing training data. Multiple tubs can be specified:

--tub ./data/tub_1 ./data/tub_2 ./data/tub_3

--model

string

Output path and filename for the trained model. Example: ./models/pilot.h5If not specified, a default name will be generated based on the model type and timestamp.

--type

string

Model architecture type to use for training. Common types:

linear: Simple linear model (fastest, least accurate)
categorical: Categorical output model
inferred: Model with inferred steering
latent: Latent space model

If not specified, uses DEFAULT_MODEL_TYPE from config.

--config

string

default:"./config.py"

Location of the config file to use. Default is ./config.py in the current directory.

--myconfig

string

default:"./myconfig.py"

Location of your custom config overrides file. Default is ./myconfig.py.

--framework

string

default:"tensorflow"

AI framework to use for training:

tensorflow: TensorFlow/Keras (default)
pytorch: PyTorch

If not specified, uses DEFAULT_AI_FRAMEWORK from config.

--checkpoint

string

Path to a checkpoint file to resume training from (PyTorch only).

--transfer

string

Path to a pre-trained model to use as a starting point (transfer learning). The model will start with these weights and fine-tune on your data.

--comment

string

Comment to add to the model database for tracking purposes. Use double quotes for multiple words:

--comment "Training on indoor track data"

Training Process

The training process:

Loads data from specified tub(s)
Preprocesses images and normalizes inputs
Splits data into training and validation sets
Trains the model using the specified architecture
Saves the trained model to the output path
Records training history in the model database

Examples

Basic training with one tub

donkey train --tub ./data/tub_1_20-03-15 --model ./models/pilot.h5

Train with multiple tubs

donkey train --tub ./data/tub_1 ./data/tub_2 ./data/tub_3 --model ./models/multi_tub.h5

Train with specific model type

donkey train --tub ./data/tub_1 --model ./models/pilot.h5 --type linear

Use PyTorch instead of TensorFlow

donkey train --tub ./data/tub_1 --model ./models/pilot.h5 --framework pytorch

Resume training from checkpoint (PyTorch)

donkey train --tub ./data/tub_1 --model ./models/pilot.h5 \
  --framework pytorch --checkpoint ./models/checkpoint_epoch_10.pth

Transfer learning from existing model

donkey train --tub ./data/new_track --model ./models/new_track_pilot.h5 \
  --transfer ./models/pilot.h5

Add a comment for tracking

donkey train --tub ./data/tub_1 --model ./models/pilot.h5 \
  --comment "First training session on outdoor track"

Use custom config file

donkey train --tub ./data/tub_1 --model ./models/pilot.h5 \
  --config ./custom_config.py --myconfig ./my_overrides.py

Training Output Example

Using TensorFlow backend
Loading tubs from paths: ./data/tub_1
Tub 1: 2,487 records
Total records: 2,487
Training records: 1,989
Validation records: 498

Model type: linear
Input shape: (120, 160, 3)
Output: angle, throttle

Training...
Epoch 1/100
62/62 [==============================] - 8s 125ms/step - loss: 0.0856 - angle_loss: 0.0421 - throttle_loss: 0.0435 - val_loss: 0.0234
Epoch 2/100
62/62 [==============================] - 7s 118ms/step - loss: 0.0198 - angle_loss: 0.0098 - throttle_loss: 0.0100 - val_loss: 0.0156
...
Epoch 35/100
62/62 [==============================] - 7s 117ms/step - loss: 0.0045 - angle_loss: 0.0021 - throttle_loss: 0.0024 - val_loss: 0.0123

Stopped early on epoch: 35
Saving model: ./models/pilot.h5
Model saved.

Configuration Options

Key configuration parameters in config.py / myconfig.py:

# Model settings
DEFAULT_MODEL_TYPE = 'linear'
DEFAULT_AI_FRAMEWORK = 'tensorflow'

# Training settings
BATCH_SIZE = 128
TRAIN_TEST_SPLIT = 0.8
MAX_EPOCHS = 100
SHOW_PLOT = True
VERBOSE_TRAIN = True

# Image settings
IMAGE_W = 160
IMAGE_H = 120
IMAGE_DEPTH = 3

# Model behavior
MIN_STEERING = -1.0
MAX_STEERING = 1.0
MIN_THROTTLE = -1.0
MAX_THROTTLE = 1.0

# Early stopping
EARLY_STOP_PATIENCE = 5
MIN_DELTA = 0.0005

Model Types

Linear Model

Simple fully-connected network. Fast training, good for simple tracks.

donkey train --tub ./data/tub_1 --model ./models/pilot.h5 --type linear

Categorical Model

Outputs discrete steering categories instead of continuous values.

donkey train --tub ./data/tub_1 --model ./models/pilot.h5 --type categorical

Custom Models

You can define custom model architectures in your config file.

Transfer Learning

Transfer learning allows you to start with a pre-trained model and fine-tune it on new data:

donkey train --tub ./data/new_track --model ./models/new_pilot.h5 \
  --transfer ./models/old_pilot.h5

Benefits:

Faster training time
Better performance with less data
Leverage knowledge from previous tracks

Use cases:

Training on a new track similar to previous tracks
Adapting to different lighting conditions
Fine-tuning for specific sections of a track

Tips for Better Training

Data Collection

Quantity: Collect at least 10-20 laps of good driving data
Quality: Drive smoothly and consistently
Diversity: Include various scenarios (straight, curves, lighting)
Recovery: Include recovery maneuvers from edge positions

Training Strategy

Start simple: Begin with a linear model to verify your pipeline
Monitor validation loss: Watch for overfitting (validation loss increasing while training loss decreases)
Use early stopping: Configured via EARLY_STOP_PATIENCE in config
Experiment with augmentation: Enable data augmentation in config

Data Augmentation

Enable augmentation in your config to increase training data diversity:

# In myconfig.py
AUG_FLIP_HORIZONTAL = True
AUG_CROP_CHANCE = 0.8
AUG_CROP_TOP = 0.2
AUG_BLUR_CHANCE = 0.2
AUG_BRIGHTNESS_RANGE = (0.5, 1.5)

Troubleshooting

Low accuracy / High validation loss

Collect more diverse training data
Try a more complex model architecture
Enable data augmentation
Verify calibration values are correct

Overfitting (validation loss increasing)

Reduce model complexity
Enable data augmentation
Collect more diverse data
Reduce number of epochs

Out of memory errors

Reduce BATCH_SIZE in config
Reduce image resolution (IMAGE_W, IMAGE_H)
Close other applications
Use a machine with more RAM/GPU memory

Model file not found

Ensure the models/ directory exists
Check file path is correct and absolute
Verify write permissions

Next Steps

After training:

Test your model: Use donkey tubplot to visualize predictions
Create a video: Use donkey makemovie to see model performance
Run autonomous mode: Test on your car with python manage.py drive --model ./models/pilot.h5
Iterate: Collect more data where the model struggles and retrain
Track models: Use donkey models to view your model database

Commands

Usage

Options

Training Process

Examples

Basic training with one tub

Train with multiple tubs

Train with specific model type

Use PyTorch instead of TensorFlow

Resume training from checkpoint (PyTorch)

Transfer learning from existing model

Add a comment for tracking

Use custom config file

Training Output Example

Configuration Options

Model Types

Linear Model

Categorical Model

Custom Models

Transfer Learning

Tips for Better Training

Data Collection

Training Strategy

Data Augmentation

Troubleshooting

Low accuracy / High validation loss

Overfitting (validation loss increasing)

Out of memory errors

Model file not found

Next Steps

Build docs developers (and LLMs) love

Commands

​Usage

​Options

​Training Process

​Examples

​Basic training with one tub

​Train with multiple tubs

​Train with specific model type

​Use PyTorch instead of TensorFlow

​Resume training from checkpoint (PyTorch)

​Transfer learning from existing model

​Add a comment for tracking

​Use custom config file

​Training Output Example

​Configuration Options

​Model Types

​Linear Model

​Categorical Model

​Custom Models

​Transfer Learning

​Tips for Better Training

​Data Collection

​Training Strategy

​Data Augmentation

​Troubleshooting

​Low accuracy / High validation loss

​Overfitting (validation loss increasing)

​Out of memory errors

​Model file not found

​Next Steps

Build docs developers (and LLMs) love

Usage

Options

Training Process

Examples

Basic training with one tub

Train with multiple tubs

Train with specific model type

Use PyTorch instead of TensorFlow

Resume training from checkpoint (PyTorch)

Transfer learning from existing model

Add a comment for tracking

Use custom config file

Training Output Example

Configuration Options

Model Types

Linear Model

Categorical Model

Custom Models

Transfer Learning

Tips for Better Training

Data Collection

Training Strategy

Data Augmentation

Troubleshooting

Low accuracy / High validation loss

Overfitting (validation loss increasing)

Out of memory errors

Model file not found

Next Steps