donkey models

View the model training database and history

The donkey models command displays a database of your trained models, showing training history, tub data used, and performance metrics.

Usage

cd ~/mycar
donkey models [--config <path>] [--group]

Arguments

--config · string · default: "./config.py"

Path to your config.py file

--group · boolean · default: "false"

Group tubs and plot them separately in the output

Description

Donkeycar maintains a database of your training history in the models/ directory. The models command displays:

• Pilot information - Model names, types, timestamps
• Training tubs - Which data was used to train each model
• Performance metrics - Loss values, training duration
• Model relationships - Transfer learning lineage

Example Output

cd ~/mycar
donkey models

Output:

┌──────────────────────┬─────────────┬────────────┬──────────────┬─────────┐
│ Name                 │ Type        │ Tubs       │ Date         │ Loss    │
├──────────────────────┼─────────────┼────────────┼──────────────┼─────────┤
│ mypilot_22-01-15.h5  │ linear      │ 1,2,3      │ 2022-01-15   │ 0.0345  │
│ fast_22-01-16.h5     │ categorical │ 1,2,3,4    │ 2022-01-16   │ 0.0289  │
│ track2_22-01-17.h5   │ linear      │ 5,6        │ 2022-01-17   │ 0.0412  │
└──────────────────────┴─────────────┴────────────┴──────────────┴─────────┘

┌──────────────────────┬────────────┬──────────┬─────────────┐
│ Tub                  │ Records    │ Date     │ Size        │
├──────────────────────┼────────────┼──────────┼─────────────┤
│ tub_1_22-01-10       │ 2,341      │ 01-10    │ 1.2 GB      │
│ tub_2_22-01-11       │ 1,892      │ 01-11    │ 890 MB      │
│ tub_3_22-01-12       │ 3,105      │ 01-12    │ 1.5 GB      │
└──────────────────────┴────────────┴──────────┴─────────────┘

Use Cases

1. Track Training Progress

See which models you’ve trained and when:

donkey models

Helps you:

• Remember which model performed best
• Track training experiments
• See which data was used for each model

2. Audit Data Usage

Verify which tubs contributed to each model:

donkey models --group

Useful for:

• Ensuring balanced training data
• Tracking down data quality issues
• Understanding model behavior based on training data

3. Model Management

Identify old models to delete:

donkey models
# Review output, then:
rm models/old_model_22-01-10.h5

Database Location

The model database is stored in:

~/mycar/models/
  ├── database.json         # Training history
  ├── mypilot_22-01-15.h5  # Model files
  └── ...

Information Displayed

Pilot Table

• Name - Model filename
• Type - Model architecture (linear, categorical, lstm, etc.)
• Tubs - Comma-separated list of tub indices used in training
• Date - Training date
• Loss - Final validation loss (lower is better)
• Val Loss - Validation set loss
• Transfer - Parent model if using transfer learning
• Comment - User comment added during training

Tub Table

• Tub - Tub directory name
• Records - Number of data records
• Date - Collection date
• Size - Disk space used
• Sessions - Number of recording sessions

Using —group Flag

donkey models --group

The --group flag organizes the output by grouping tubs together that were used in the same training runs. This makes it easier to see training patterns and data relationships.

Model Database Schema

The database.json file stores training metadata:

{
  "pilots": [
    {
      "name": "mypilot_22-01-15.h5",
      "type": "linear",
      "tubs": ["tub_1", "tub_2", "tub_3"],
      "date": "2022-01-15T10:30:00",
      "loss": 0.0345,
      "val_loss": 0.0389,
      "transfer": null,
      "comment": "First working model"
    }
  ],
  "tubs": [
    {
      "path": "./data/tub_1_22-01-10",
      "records": 2341,
      "date": "2022-01-10"
    }
  ]
}

Adding Comments to Models

When training, add comments to track experiments:

donkey train --tub ./data --model ./models/mypilot.h5 \
  --comment "Trained on straight sections only"

Comments appear in the database and help you remember model purposes.

Troubleshooting

No models found

If the command shows no models:

• Ensure you’re in your car directory: cd ~/mycar
• Check models directory exists: ls models/
• Train a model first with donkey train
• Database might be corrupted, check models/database.json

Database file not found

If database.json is missing:

• The database is created during training
• Train a new model to recreate it
• Or create empty database: echo '{"pilots": [], "tubs": []}' > models/database.json

Incorrect or missing information

If database information is wrong:

• The database is updated during training, not retroactively
• Old models trained before database feature won’t appear
• You can manually edit models/database.json (valid JSON required)

Related Commands

• donkey train - Train models (creates database entries)
• donkey tubplot - Compare model predictions
• donkey makemovie - Visualize model performance

Tips

Name models descriptively - Use meaningful names that indicate track, date, or purpose:

donkey train --tub ./data --model models/track2_fast_22-01-15.h5

Clean old models regularly - Delete underperforming models to save space:

donkey models  # review performance
rm models/bad_model.h5  # delete poor performers

Track experiments - Always add comments when trying new architectures or training strategies:

--comment "LSTM with 128 units, dropout 0.2"

Source Code

Implemented in:

• donkeycar/management/base.py:573-592 - CLI command
• donkeycar/pipeline/database.py - PilotDatabase class

Further Reading

• Training Documentation
• Model Architectures
• Data Management