TelloPy: scripting the DJI Tello drone from Python

A Go driver ported to Python, and what that buys

TelloPy is a Python package that controls the DJI toy drone Tello. The README states where the code came from: the major portion of the source code was ported from the driver of the GOBOT project, and for the original Go version and the protocol in detail it points at the GOBOT blog post on hacking the Tello with Go.

That origin explains both the shape of the package and its limits. The protocol implementation is a translation of a working Go implementation, which means the hard part, decoding the drone's UDP command and telemetry protocol, has already been solved and was solved by a project that had documented it publicly. The Python layer is the binding surface, the examples and the packaging.

The audience is the developer or student who wants the drone to do something a phone app cannot express. Tello is a toy drone with a documented command interface, and a script can chain takeoff, movement and rotation without the video feed being the only output, which is what makes it useful for computer vision experiments where the drone has to react to what it sees.

The repository layout is small: a `tellopy/` package directory, `tests/`, `docs/`, a `setup.py`, a `setup.cfg`, a `test_xbox.py` at the root, a `files/` directory holding images used in the README, and a CHANGELOG.md. The `files/` directory is where the drone and gamepad photo and the video effect screenshot live.

The package version in setup.py is 0.8.0.dev0, the default branch is develop-0.8.0, and the last push was on 2026-10-03. The licence is one GitHub cannot classify, and it is the LICENSE.txt file in the repository root.

Installing from PyPI or building a wheel yourself

There are two installation routes, and the second one is the one that gets you the current development version.

The stable version comes from PyPI:

$ pip install tellopy

Or you install from the source code:

$ git clone https://github.com/hanyazou/TelloPy 
$ cd TelloPy
$ python setup.py bdist_wheel
$ pip install dist/tellopy-*.dev*.whl --upgrade

Note the shape of the source install. It builds a wheel with `python setup.py bdist_wheel` and then installs the resulting dev wheel with the `--upgrade` flag, and the glob pattern matches on `tellopy-*.dev*.whl`, which corresponds to the 0.8.0.dev0 version in setup.py. That is the practical way to get the code on the develop-0.8.0 branch rather than whatever is on PyPI.

The version support is declared in the setup metadata rather than enforced by dependencies. `python_requires` is `>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, <4`, and the classifiers list Python 2.7, 3.5 and 3.6, with the general Python 2 and Python 3 classifier lines and the 3.4 line commented out. The development status classifier is 3, Alpha, and the licence classifier is Apache Software License.

The `install_requires` list is empty, which is worth pausing on. The core package declares no runtime dependencies at all, which means the drone protocol layer uses nothing outside the standard library. The extra packages you need are the ones the examples require, and they are installed separately, per example.

For reading the API, the README points at the docstring, which is accessible from an interactive Python session:

$ python
>>> import tellopy
>>> help(tellopy)
Help on package tellopy:
...

Three examples that show what the package is for

The examples folder is where the value of the package becomes concrete, and the README walks through three of them.

The first is simple_takeoff, which lets Tello take off, with the drone landing automatically after a few seconds:

$ python -m tellopy.examples.simple_takeoff

The second is video_effect, which filters and displays the realtime video stream from Tello:

$ pip install av
$ pip install opencv-python
$ pip install image
$ python -m tellopy.examples.video_effect

The dependency list for that example is the clearest statement of the stack. PyAV handles the video decoding, OpenCV does the frame processing, and the `image` package is the third dependency. That is a sensible division: PyAV handles the decoding and OpenCV the filtering.

The third is joystick_and_video, which uses a PS3, PS4 or XONE joystick to control the drone:

$ pip install av
$ pip install opencv-python
$ pip install image
$ pip install pygame
$ python -m tellopy.examples.joystick_and_video

Pygame is the addition here, and it is doing double duty: it reads the gamepad, and it provides the window in which the video is displayed. A single dependency covering input and display is an efficient choice for an example, and it is also why the `test_xbox.py` file at the repository root exists, since Xbox controllers are the awkward case for pygame's joystick handling.

The third example combines the two interesting capabilities of the drone at once: manual control and live video, which is what a human would want when learning to fly it under program control. The README links a video of it working.

Because the dependencies are per example, you install only what the one you want needs, and a bare `pip install tellopy` gives you the flight control with no video stack at all.

Two community projects that show the extension path

The README points at two side projects, and they are worth reading because they show what the package enables and what it does not do.

The first is a hand motion Tello controller at the HalloPy repository, which lets you control the drone using hand movements. The second is an OpenCV based Tello controller at the telloCV repository, which interfaces with the drone through OpenCV and generates frames from the video stream for computer vision applications, and comes with a tracker that detects a colour in the scene and follows it.

Both are the same shape of extension: use the drone's video stream as the input to a computer vision routine, and use the flight commands as the output. A colour tracker that follows a red ball around a room is the canonical example, and it is the clearest demonstration of why scripting the drone is more than a toy.

Neither extension is part of this package. That is a signal about the boundaries of the library, and it is a healthy one. TelloPy provides the flight and video plumbing, and the interesting applications are built on top of it by other people, with the vision stack being the user's choice rather than a dependency the library imposes.

The drone itself is a toy, and that shows up in the design. The protocol is a documented command interface over the network rather than a flight controller API, the command vocabulary is small, and the failure modes are the ones you would expect from a consumer drone with a consumer price: limited flight time, and a vehicle that needs a clear space. The package does not change any of that.

The side projects are also where the maintenance question becomes concrete. The last tagged release is v0.6.0, from 2018, and the two side projects predate the current development branch as well. A colour tracker built on a 2018 release of the video API is a different amount of work to port than one built on 0.8.0.dev0, and there is no version compatibility matrix in the repository to tell you which is which.

Against the official SDK and against a phone with an app

The comparison worth making is with the two other ways to fly a Tello from a computer.

The first is the manufacturer's own tooling. DJI provides an app for the Tello, and a drone that works well with a phone app does not need a Python package to be fun. The difference in approach is what a script can do that an app cannot. An app gives a human a control surface: a stick, a button, a preview. A script gives a program a control surface: a sequence of commands with timing, branching on telemetry, and a video stream it can process and act on. The package's own examples exist because that second thing is not what the app is for.

The second alternative is talking to the drone directly. The Tello protocol is a documented UDP command interface, and it is possible to write the socket handling yourself, which is roughly what the GOBOT project did in Go. Doing that gives you full control and no dependency, and it also means you own the protocol details, the retry behaviour on a dropped packet, the video stream parsing, and every quirk that the Go driver already worked out. The TelloPy port exists so that you do not have to.

The trade is the usual one between a library and a dependency. TelloPy gives you a working driver in an afternoon, with the protocol already decoded and the examples already written. It also gives you a package whose tagged releases stop in 2018, whose setup metadata still describes Python 2.7 as supported, and whose version compatibility with your own drone firmware is not documented anywhere in the repository.

That last point is the one to check first in practice. The drone's firmware determines what the protocol accepts, and nothing in the repository says which firmware versions the package was tested against, so the two can in principle disagree about protocol details. Nothing in the repository states which firmware versions the 0.8.0 development branch was tested against.

Against the official app and against talking to the drone yourself

The comparison worth making is with the two other ways to fly a Tello from a computer.

The first is the manufacturer's own tooling. DJI provides an app for the Tello, and a drone that works well with a phone app does not need a Python package to be fun. The difference in approach is what a script can do that an app cannot. An app gives a human a control surface: a stick, a button, a preview. A script gives a program a control surface: a sequence of commands with timing, branching on telemetry, and a video stream it can process and act on. The package's own examples exist because that second thing is not what the app is for.

The second alternative is talking to the drone directly. The Tello protocol is a documented UDP command interface, and it is possible to write the socket handling yourself, which is roughly what the GOBOT project did in Go. Doing that gives you full control and no dependency, and it also means you own the protocol details, the retry behaviour on a dropped packet, the video stream parsing, and every quirk that the Go driver already worked out. The TelloPy port exists so that you do not have to.

The trade is the usual one between a library and a dependency. TelloPy gives you a working driver in an afternoon, with the protocol already decoded and the examples already written. It also gives you a package whose tagged releases stop in 2018, whose setup metadata still describes Python 2.7 as supported, and whose version compatibility with your own drone firmware is not documented anywhere in the repository.

That last point is the one to check first in practice. The drone's firmware determines what the protocol accepts, and the project's own recommendation when something does not work is to test the same operation side by side with the original driver, which implies the two can disagree about protocol details. Nothing in the repository states which firmware versions the 0.8.0 development branch was tested against.

Editorial conclusion

Adopt TelloPy if you want to program a DJI Tello in Python, for teaching, experiments or computer vision work, and read the example folder before writing anything new. Do not adopt it as a maintained library, because the tagged releases stop at v0.6.0 from 2018 while the working tree sits on a 0.8.0 development branch, and check first that the drone's own firmware and your Python version still match what the package expects, since the install_requires list is empty and the version support is declared only in the setup metadata.

Frequently asked questions

Official sources

1. hanyazou/TelloPy on GitHub
2. Issues
3. README
4. Releases