Skip to main content

A pythonic Xbox360 controller API built on top of the xpad Linux kernel driver.

Project description


A pythonic Xbox360 controller API built on top of the xpad Linux kernel driver.

PyPI Version Build Status Code Health

This Python Package aims to provide a pythonic and complete API for your Xbox360 and similar game controllers. Currently it's built on top of the Linux kernel driver xpad so you can use it on almost any Linux distribution including your Rasperry Pi projects etc.

The following features are supported:

  • Registering callbacks for all Buttons, Axes, Triggers and Hat in a gpiozero-inspired way
  • Setting the LED circle; all xpad provided options are possible: blinking, rotating, setting individual LEDs on and off, ...
  • Rumbling, both the left and right side can be controlled from 0 to 100 percent


You will need Python 3.4 or above.

Any Linux distribution:

pip3 install -U xbox360controller

You might also use a virtual environment or do a per-user install by providing the --user flag to above command. Global installations might require the usage of sudo or working directly from a root shell but are not recommended.

If the pip3 command cannot be found, try pip or make sure to have pip installed properly:

sudo apt install python3-pip

Of course you don't need sudo when working from a root shell.



import signal
from xbox360controller import Xbox360Controller

def on_button_pressed(button):
    print('Button {0} was pressed'.format(

def on_button_released(button):
    print('Button {0} was released'.format(

def on_axis_moved(axis):
    print('Axis {0} moved to {1} {2}'.format(, axis.x, axis.y))

    with Xbox360Controller(0, axis_threshold=0.2) as controller:
        # Button A events
        controller.button_a.when_pressed = on_button_pressed
        controller.button_a.when_released = on_button_released

        # Left and right axis move event
        controller.axis_l.when_moved = on_axis_moved
        controller.axis_r.when_moved = on_axis_moved

except KeyboardInterrupt:

The above code will run until Ctrl+C is pressed. Each time on of the left or right axis is moved, the event will be processed. Additionally, the events of the A button are being processed.

See the API reference for a more detailed explanation of the Xbox360Controller class and how to use all available buttons, axes and the hat.


import time
from xbox360controller import Xbox360Controller

with Xbox360Controller() as controller:
    controller.set_rumble(0.5, 0.5, 1000)

This will enable rumble on both sides of the controller with each 50% strength for one second (1000ms). Note that the method call is non-blocking, thus we need to manually wait one second for the rumble to finish. You won't need this in a regular use case with signal.pause().


import time
from xbox360controller import Xbox360Controller

with Xbox360Controller() as controller:

This will let the LED circle rotate for one second and then turn it off.

See the API reference for all available LED modes.

Debug information

from xbox360controller import Xbox360Controller

with Xbox360Controller() as controller:


This project is now in a somewhat stable state, and I really appreciate all kinds of contributions - may it be new or improved code, documentation or just a simple typo fix. Just provide me a PR and I'll be happy to include your work!

For feature requests, general questions or problems you face regarding this package please open an issue.

Release History

Please see for a complete release history.



All the code and documentation are distributed under the MIT license. See LICENSE for more information.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for xbox360controller, version 1.1.2
Filename, size File type Python version Upload date Hashes
Filename, size xbox360controller-1.1.2.tar.gz (11.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page