Donkeycar: a python self driving library

Donkeycar is a minimalist and modular self driving library for Python. It is developed for hobbyists and students with a focus on allowing fast experimentation and easy community contributions. It is being actively used at the high school and university level for learning and research. It offers a rich graphical interface and includes a simulator so you can experiment with self-driving even before you build a robot.

Quick Links

• Donkeycar Updates & Examples
• Build instructions and Software documentation
• Discord / Chat

Use Donkeycar if you want to:

• Build a robot and teach it to drive itself.
• Experiment with autopilots, gps, computer vision and neural networks.
• Compete in self driving races like DIY Robocars, including online simulator races against competitors from around the world.
• Participate in a vibrant online community learning cutting edge techology and having fun doing it.

What do you need to know before starting? (TL;DR nothing)

Donkeycar is designed to be the 'Hello World' of automomous driving; it is simple yet flexible and powerful. No specific prequisite knowledge is required, but it helps if you have some knowledge of:

• Python programming. You do not have to do any programming to use Donkeycar. The file that you edit to configure your car, myconfig.py, is a Python file. You mostly just uncomment the sections you want to change and edit them; you can avoid common mistakes if you know how Python comments and indentation works.
• Raspberry Pi. The Raspberry Pi is the preferred on-board computer for a Donkeycar. It is helpful to have setup and used a Raspberry Pi, but it is not necessary. The Donkeycar documentation describes how to install the software on a RaspberryPi OS, but the specifics of how to install the RaspberryPi OS using Raspberry Pi Imager and how to configure the Raspberry Pi using raspi-config is left to the Raspberry Pi documentation, which is extensive and quite good. I would recommend setting up your Raspberry Pi using the Raspberry Pi documentation and then play with it a little; use the browser to visit websites and watch YouTube videos, like this one taken at the very first outdoor race for a Donkeycar. Use a text editor to write and save a file. Open a terminal and learn how to navigate the file system (see below). If you are comfortable with the Raspberry Pi then you won't have to learn it and Donkeycar at the same time.
• The Linux command line shell. The command line shell is also often called the terminal. You will type commands into the terminal to install and start the Donkeycar software. The Donkeycar documentation describes how this works. It is also helpful to know how navigate the file system and how to list, copy and delete files and directories/folders. You may also access your car remotely; so you will want to know how to enable and connect WIFI and how to enable and start an SSH terminal or VNC session from your host computer to get a command line on your car.

Get driving.

After building a Donkeycar and installing the Donkeycar software you can choose your autopilot template and calibrate your car and get driving!

Modify your car's behavior.

Donkeycar includes a number of pre-built templates that make it easy to get started by just changing configuration. The pre-built templates are all you may ever need, but if you want to go farther you can change a template or make your own. A Donkeycar template is organized as a pipeline of software parts that run in order on each pass through the vehicle loop, reading inputs and writing outputs to the vehicle's software memory as they run. A typical car has a parts that:

• Get images from a camera. Donkeycar supports lots of different kinds of cameras, including 3D cameras and lidar.
• Get position readings from a GPS receiver.
• Get steering and throttle inputs from a game controller or RC controller. Donkeycar support PS3, PS4, XBox, WiiU, Nimbus and Logitech Bluetooth game controllers and any game controller that works with RaspberryPi. Donkeycar also implements a WebUI that allows any browser compatible game controller to be connected and also offers an onscreen touch controller that works with phones.
• Control the car's drivetrain motors for acceleration and steering. Donkeycar supports various drivetrains including the ESC/Steering-servo configuration that is common to most RC cars and Differential Drive configurations.
• Save telemetry data such as camera images, steering and throttle inputs, lidar data, etc.
• Drive the car on autopilot. Donkey supports three kinds of autopilots; a deep-learning autopilot, a gps autopilot and a computer vision autopilot. The Deep Learning autopilot supports Tensorflow, Tensorflow Lite, and Pytorch and many model architectures.

If there isn't a Donkeycar part that does what you want then write your own part and add it to a vehicle template.

#Define a vehicle to take and record pictures 10 times per second.

import time
from donkeycar import Vehicle
from donkeycar.parts.cv import CvCam
from donkeycar.parts.tub_v2 import TubWriter
V = Vehicle()

IMAGE_W = 160
IMAGE_H = 120
IMAGE_DEPTH = 3

#Add a camera part
cam = CvCam(image_w=IMAGE_W, image_h=IMAGE_H, image_d=IMAGE_DEPTH)
V.add(cam, outputs=['image'], threaded=True)

#warmup camera
while cam.run() is None:
    time.sleep(1)

#add tub part to record images
tub = TubWriter(path='./dat', inputs=['image'], types=['image_array'])
V.add(tub, inputs=['image'], outputs=['num_records'])

#start the drive loop at 10 Hz
V.start(rate_hz=10)

Installation

Donkeycar uses uv for environment management. Install uv first:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then create a persistent virtual environment and activate it on login by adding the source line to your shell profile.

Raspberry Pi

Camera support (picamera2, libcamera) requires system packages that are not on PyPI. Install them first:

sudo apt install python3-libcamera python3-picamera2

Then create the venv using the system Python (3.13 on Raspberry Pi OS Trixie) with --system-site-packages so the venv can see the camera libraries:

uv venv ~/env --python 3.13 --system-site-packages
echo 'source ~/env/bin/activate' >> ~/.zshrc
source ~/env/bin/activate

User install (from PyPI):

uv pip install donkeycar[pi]

Developer install (from a git clone):

uv pip install -e ".[pi,dev]"

Mac

uv venv ~/.venvs/donkeycar --python 3.12
echo 'source ~/.venvs/donkeycar/bin/activate' >> ~/.zshrc
source ~/.venvs/donkeycar/bin/activate

User install (from PyPI):

uv pip install donkeycar[macos]

Developer install (from a git clone):

uv pip install -e ".[macos,dev]"

PC (Linux/Windows)

uv venv ~/.venvs/donkeycar --python 3.12
echo 'source ~/.venvs/donkeycar/bin/activate' >> ~/.zshrc
source ~/.venvs/donkeycar/bin/activate

User install (from PyPI):

uv pip install donkeycar[pc]

Developer install (from a git clone):

uv pip install -e ".[pc,dev]"

Once the venv is activated in your shell profile the donkey command is available from any directory without needing uv run.

See home page, docs or join the Discord server to learn more.