Skip to main content
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 4 or 5 (recommended: 4GB+ RAM)
  • Raspberry Pi OS (64-bit recommended)
  • MicroSD card (32GB+ recommended)
  • Camera (Pi Camera Module or USB webcam)

​
Installation by Platform

​
Raspberry Pi

1
Install System Dependencies
2
Update your system and install required packages:
3
sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y python3-dev python3-pip python3-venv
sudo apt-get install -y libhdf5-dev libatlas-base-dev libjasper-dev
sudo apt-get install -y libqtgui4 libqt4-test git
4
Create Virtual Environment
5
It’s recommended to use a virtual environment:
6
python3 -m venv ~/donkey
source ~/donkey/bin/activate
7
Add source ~/donkey/bin/activate to your ~/.bashrc to automatically activate the environment on login.
8
Install Donkeycar with Raspberry Pi Dependencies
9
pip install --upgrade pip
pip install donkeycar[pi]
10
This installs Donkeycar along with Raspberry Pi-specific dependencies:
11
  • picamera2 - Raspberry Pi Camera interface
  • Adafruit_PCA9685 - I2C PWM controller
  • adafruit-circuitpython-ssd1306 - OLED display support
  • adafruit-circuitpython-rplidar - Lidar support
  • RPi.GPIO - GPIO pin control
  • tflite-runtime - TensorFlow Lite for inference
  • opencv-contrib-python - Computer vision
  • matplotlib - Plotting and visualization
  • kivy - UI framework
  • albumentations - Image augmentation
    • 12
    The [pi] extra automatically installs all dependencies needed for Raspberry Pi, including camera support and TensorFlow Lite.
    13
    Enable Camera
    14
    For Raspberry Pi Camera Module:
    15
    sudo raspi-config
    16
    Navigate to: Interface Options → Camera → Enable
    17
    Reboot after enabling:
    18
    sudo reboot
    19
    Test Camera
    20
    Test the Raspberry Pi Camera:
    21
    libcamera-hello --list-cameras
    22
    Or take a test photo:
    23
    libcamera-still -o test.jpg
    24
    Verify Installation
    25
    donkey --help
    26
    You should see the Donkey Car welcome message and available commands.

    ​
    Jetson Nano

    1
    Prerequisites
    2
    Ensure you have JetPack installed (includes CUDA and cuDNN):
    3
    sudo apt-get update
sudo apt-get upgrade -y
    4
    Create Virtual Environment
    5
    python3 -m venv ~/donkey
source ~/donkey/bin/activate
    6
    Install Donkeycar with Jetson Nano Dependencies
    7
    pip install --upgrade pip
pip install donkeycar[nano]
    8
    Jetson Nano-specific dependencies include:
    9
  • Adafruit_PCA9685 - I2C PWM controller
  • adafruit-circuitpython-ssd1306 - OLED display
  • adafruit-circuitpython-rplidar - Lidar support
  • Jetson.GPIO - GPIO control for Jetson
  • numpy==1.23.* - Compatible NumPy version
  • matplotlib==3.7.* - Visualization
  • pandas==2.0.* - Data processing
  • kivy - UI framework
  • plotly - Interactive plots
    • 10
    The [nano] extra uses specific versions of NumPy, Matplotlib, and Pandas that are compatible with the Jetson Nano’s ARM architecture and CUDA libraries.
    11
    Install TensorFlow for Jetson
    12
    For GPU-accelerated training on Jetson Nano:
    13
    # Install TensorFlow for Jetson (provided by NVIDIA)
sudo pip3 install --extra-index-url https://developer.download.nvidia.com/compute/redist/jp/v46 tensorflow==2.7.0+nv22.1
    14
    Verify Installation
    15
    donkey --help
python -c "import tensorflow as tf; print(tf.__version__)"

    ​
    PC (Linux/Windows WSL)

    1
    Install System Dependencies (Linux)
    2
    On Ubuntu/Debian:
    3
    sudo apt-get update
sudo apt-get install -y python3-dev python3-pip python3-venv
sudo apt-get install -y libhdf5-dev
    4
    Create Virtual Environment
    5
    python3 -m venv ~/donkey
source ~/donkey/bin/activate
    6
    For Windows WSL, the same commands work in your WSL terminal.
    7
    Install Donkeycar with PC Dependencies
    8
    pip install --upgrade pip
pip install donkeycar[pc]
    9
    PC-specific dependencies include:
    10
  • tensorflow==2.15.* - Full TensorFlow with training support
  • matplotlib - Plotting
  • kivy - UI framework
  • kivy-garden.matplotlib - Matplotlib integration for Kivy
  • pandas - Data processing
  • plotly - Interactive visualizations
  • albumentations - Image augmentation for training
    • 11
    The PC installation includes full TensorFlow for training models, unlike the Pi installation which uses TensorFlow Lite for inference only.
    12
    Optional: Install with PyTorch Support
    13
    For PyTorch-based models:
    14
    pip install donkeycar[pc,torch]
    15
    This adds:
    16
  • torch==2.1.* - PyTorch framework
  • pytorch-lightning - PyTorch training framework
  • torchvision - Computer vision for PyTorch
  • torchaudio - Audio processing
  • fastai - Fast.ai deep learning library
    • 17
    Verify Installation
    18
    donkey --help
python -c "import tensorflow as tf; print(tf.__version__)"

    ​
    macOS

    1
    Install Python 3.11
    2
    Using Homebrew:
    3
    brew install [email protected]
    4
    Verify:
    5
    python3.11 --version
    6
    Create Virtual Environment
    7
    python3.11 -m venv ~/donkey
source ~/donkey/bin/activate
    8
    Install Donkeycar with macOS Dependencies
    9
    For Apple Silicon Macs (M1/M2/M3) with GPU acceleration:
    10
    pip install --upgrade pip
pip install donkeycar[macos]
    11
    For Intel Macs:
    12
    pip install donkeycar[pc]
    13
    macOS-specific dependencies include:
    14
  • tensorflow==2.15.* - TensorFlow
  • tensorflow-metal - GPU acceleration for Apple Silicon
  • matplotlib - Plotting
  • kivy - UI framework
  • pandas - Data processing
  • plotly - Visualization
  • albumentations - Image augmentation
    • 15
    The [macos] extra includes tensorflow-metal for GPU acceleration on Apple Silicon Macs. This can significantly speed up training.
    16
    Optional: PyTorch for macOS
    17
    pip install donkeycar[macos,torch]
    18
    Verify Installation
    19
    donkey --help
python -c "import tensorflow as tf; print(tf.__version__)"

    ​
    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: 
    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

    1
    Test the Installation
    2
    Verify all components are working:
    3
    # Check Donkeycar version
python -c "import donkeycar; print(donkeycar.__version__)"

# Test TensorFlow (if installed)
python -c "import tensorflow as tf; print(tf.__version__)"

# Test PyTorch (if installed)
python -c "import torch; print(torch.__version__)"
    4
    Find Your Car (Raspberry Pi/Jetson)
    5
    From your host computer, find your car’s IP address:
    6
    donkey findcar
    7
    Or on the car itself:
    8
    hostname -I
    9
    Enable SSH (Raspberry Pi)
    10
    For remote access:
    11
    sudo raspi-config
    12
    Navigate to: Interface Options → SSH → Enable
    13
    Configure WiFi
    14
    Ensure your car has a stable WiFi connection. Edit the WiFi configuration:
    15
    sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
    16
    Add your network:
    17
    network={
    ssid="YourNetworkName"
    psk="YourPassword"
}

    ​
    Upgrading Donkeycar

    To upgrade to the latest version: 
    pip install --upgrade donkeycar
    To upgrade with platform-specific dependencies: 
    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

    Donkeycar requires Python 3.11.x. Check your version:
    python --version
    If you have multiple Python versions, use:
    python3.11 -m venv ~/donkey
    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.
    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
    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)
    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]
    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:
    When asking for help, include:
    • Your platform (Pi 4, Jetson Nano, etc.)
    • Python version (python --version)
    • Donkeycar version (pip show donkeycar)
    • Full error message

    Build docs developers (and LLMs) love

    Get started for freeTalk to us