Installation Guide

Detailed installation instructions for Donkeycar on Raspberry Pi, Jetson Nano, PC, and Mac

This guide provides detailed installation instructions for Donkeycar on different platforms.

Donkeycar requires Python 3.11. Ensure you have the correct Python version before proceeding.

System Requirements

Python Version

Donkeycar requires Python 3.11.0 or greater (but less than 3.12):

python --version
# Should output: Python 3.11.x

Donkeycar will not work with Python 3.10 or earlier, or Python 3.12 or later. You must use Python 3.11.x.

Hardware Requirements

Raspberry Pi

• Raspberry Pi 4 or 5 (recommended: 4GB+ RAM)
• Raspberry Pi OS (64-bit recommended)
• MicroSD card (32GB+ recommended)
• Camera (Pi Camera Module or USB webcam)

Jetson Nano

• NVIDIA Jetson Nano or Jetson Nano 2GB
• JetPack 4.6 or later
• MicroSD card (64GB+ recommended)
• Camera (CSI or USB)

PC/Mac

• Modern CPU (Intel/AMD/Apple Silicon)
• 8GB+ RAM recommended
• GPU optional (for faster training)
• Webcam (for testing)

Installation by Platform

Raspberry Pi

Jetson Nano

PC (Linux/Windows WSL)

macOS

Core Dependencies

All Donkeycar installations include these core dependencies:

# Core dependencies (installed with all platforms)
numpy                  # Numerical computing
pillow                 # Image processing
docopt                 # Command-line interface
tornado                # Web server
requests               # HTTP library
PrettyTable            # Terminal tables
paho-mqtt              # MQTT telemetry
simple_pid             # PID controller
progress               # Progress bars
pyfiglet               # ASCII art
psutil                 # System utilities
pynmea2                # GPS NMEA parsing
pyserial               # Serial communication
utm                    # GPS coordinate conversion
pandas                 # Data analysis
pyyaml                 # YAML configuration

Installation Extras

Donkeycar uses setuptools extras to provide platform-specific dependencies. You can combine multiple extras:

Raspberry Pi

pip install donkeycar[pi]

Available Extras

• pi - Raspberry Pi dependencies (camera, GPIO, TFLite)
• nano - Jetson Nano dependencies (Jetson GPIO, compatible library versions)
• pc - PC dependencies (full TensorFlow, training tools)
• macos - macOS dependencies (TensorFlow with Metal GPU support)
• torch - PyTorch and related libraries
• dev - Development dependencies (pytest, mypy, testing tools)

Post-Installation Steps

Upgrading Donkeycar

To upgrade to the latest version:

pip install --upgrade donkeycar

To upgrade with platform-specific dependencies:

Raspberry Pi

pip install --upgrade donkeycar[pi]

Installing from Source

For development or to use the latest unreleased features:

# Clone the repository
git clone https://github.com/autorope/donkeycar.git
cd donkeycar

# Install in editable mode
pip install -e .[pi]  # or [nano], [pc], etc.

Installing from source allows you to modify the Donkeycar code and see changes immediately without reinstalling.

Troubleshooting

Python version mismatch

Donkeycar requires Python 3.11.x. Check your version:

python --version

If you have multiple Python versions, use:

python3.11 -m venv ~/donkey

TensorFlow import error on Raspberry Pi

If you get TensorFlow errors on Raspberry Pi, ensure you installed the [pi] extras:

pip uninstall tensorflow tensorflow-lite
pip install donkeycar[pi]

The Pi uses TensorFlow Lite, not full TensorFlow.

Camera not detected (Raspberry Pi)

For Pi Camera Module:

1. Check physical connection
2. Enable camera in raspi-config
3. Test with libcamera-hello --list-cameras
4. Ensure picamera2 is installed: pip show picamera2

GPU not detected (macOS)

For Apple Silicon Macs:

1. Ensure you installed with [macos] extra
2. Verify tensorflow-metal is installed: pip show tensorflow-metal
3. Test GPU:

import tensorflow as tf
print("GPU Available:", len(tf.config.list_physical_devices('GPU')) > 0)

Memory errors during installation

If installation fails with memory errors (common on Raspberry Pi):

# Increase swap space temporarily
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile
# Change CONF_SWAPSIZE to 2048
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

# Retry installation
pip install donkeycar[pi]

ImportError: No module named 'donkeycar'

This usually means:

1. Virtual environment is not activated
2. Installed in one Python, running in another

Solution:

# Activate virtual environment
source ~/donkey/bin/activate

# Verify installation
pip list | grep donkey

Next Steps

Quick Start

Create your first car application

Configuration

Configure your car for your specific hardware

Calibration

Calibrate steering and throttle

Community

Join the Discord for help and discussions

Getting Help

If you encounter issues:

• Check the official documentation
• Search GitHub issues
• Ask on Discord in the #installation-help channel
• Review platform-specific guides in the docs

When asking for help, include:

• Your platform (Pi 4, Jetson Nano, etc.)
• Python version (python --version)
• Donkeycar version (pip show donkeycar)
• Full error message