Automatic Controller Mapping

Common game controllers are automatically configured when plugged in, just like on a real game console.

Ideal to start a multiplayer game when a friend visits with their own controller.

You can also configure everything manually, assign special actions to combos, and more!

How does it work?

RetroArch provides a set of configuration files for the most common controllers. Depending on your platform, these autoconfig profiles are either distributed with RetroArch or downloaded through the Online Updater.RetroArch provides a set of configuration files for the most common controllers. Depending on your platform, these autoconfig profiles are either distributed with RetroArch or downloaded through the Online Updater. Matching is done using 3 criteria: the device name, the vendor id and the product id. The vendor id and product id pair is often abbreviated as vid:pid. We compute a matching score for each configuration file based on these three factors. The autoconfig profile with the highest score is used to map the controller.

Why is it needed?

RetroArch works on a lot of different platforms. Each of these platforms have one or more input systems. And these input systems differ widely in the way they enumerate the pad buttons.

Standalone emulators let you map each of your controls to the original controller for the emulated system. For example, this is how the OpenEMU controller configuration looks:

The difference is that RetroArch begins by detecting your controller and automatically configuring it if possible. Manual mapping as with standalone emulators is always an option, however!


With RetroArch joypad auto configuration system, your joypad will be recognized and will work out of the box. This allows:

Having automatically configured joypads makes it a lot easier to navigate the RetroArch Menu with the joypad. This is very convenient when running RetroArch on a game console, where a keyboard and a mouse are not always available. It is also what makes RetroArch suitable to build your own game console using Lakka or a similar OS.

Controller auto configuration profiles

This is what a controller profile looks like in RetroArch.

The first part is used for matching, as explained above. The vendor id and product id are in decimal format.

The second part is the mapping itself, where each button is assigned to a button of the RetroPad (the RetroArch idealized controller abstraction).

The third part are input descriptors used by RetroArch to display the labels of the buttons as they are physically printed on your controller. For example: if you are using a DualShock pad, RetroArch will refer to the buttons as Cross, Circle, Square and Triangle. Downloading or updating joypad profiles

input_device = "Microsoft X-Box One pad"
input_driver = "udev"
input_vendor_id = 1118
input_product_id = 721

input_b_btn = "0"
input_y_btn = "2"
input_select_btn = "6"
input_start_btn = "7"
input_up_btn = "h0up"
input_down_btn = "h0down"
input_left_btn = "h0left"
input_right_btn = "h0right"
input_a_btn = "1"
input_x_btn = "3"
input_l_btn = "4"
input_r_btn = "5"
input_l2_axis = "+2"
input_r2_axis = "+5"
input_l3_btn = "9"
input_r3_btn = "10"
input_l_x_plus_axis = "+0"
input_l_x_minus_axis = "-0"
input_l_y_plus_axis = "+1"
input_l_y_minus_axis = "-1"
input_r_x_plus_axis = "+3"
input_r_x_minus_axis = "-3"
input_r_y_plus_axis = "+4"
input_r_y_minus_axis = "-4"
input_menu_toggle_btn = "8"

input_b_btn_label = "A"
input_y_btn_label = "X"
input_select_btn_label = "Back"
input_start_btn_label = "Start"
input_up_btn_label = "D-Pad Up"
input_down_btn_label = "D-Pad Down"
input_left_btn_label = "D-Pad Left"
input_right_btn_label = "D-Pad Right"
input_a_btn_label = "B"
input_x_btn_label = "Y"
input_l_btn_label = "LB"
input_r_btn_label = "RB"
input_l2_axis_label = "LT"
input_r2_axis_label = "RT"
input_l3_btn_label = "Left Thumb"
input_r3_btn_label = "Right Thumb"
input_l_x_plus_axis_label = "Left Analog X+"
input_l_x_minus_axis_label = "Left Analog X-"
input_l_y_plus_axis_label = "Left Analog Y+"
input_l_y_minus_axis_label = "Left Analog Y-"
input_r_x_plus_axis_label = "Right Analog X+"
input_r_x_minus_axis_label = "Right Analog X-"
input_r_y_plus_axis_label = "Right Analog Y+"
input_r_y_minus_axis_label = "Right Analog Y-"
input_menu_toggle_btn_label = "Guide"

Updating controller profiles

On platforms that allow the RetroArch Online Updater, you can update the set of controller profiles from the menu. Go to Main Menu->Online Updater->Update Autoconfig Profiles to get the latest version of the profile pack.

A yellow message will appear at the bottom of the screen showing the download progress and the extraction of the archive.

Generating a controller profile

If your controller is not recognized by RetroArch even after updating the profiles, or if RetroArch's matching profile is not suitable for you controller, you can generate a new profile to use.

The first step is to proceed to a manual mapping of your pad. For this, unplug all the other joypads, and use Settings->Input->User 1 Binds->User 1 Bind All. Make sure that your mapping is perfect by testing every button in the menu and in some games.

Then use Settings->Inputs->User 1 Binds->User 1 Save Autoconfig and the profile will be saved to your disk.

Important note

You should now do a Settings->Inputs->User 1 Binds->User 1 Bind Default All to reset the manual settings. Otherwise they would take precedence over the profile you generated.

Unplug your controller an re-plug it. See if it is auto configured.

If you are happy with your profile, you can write the input descriptors part and submit your profile in our git repository.

Troubleshooting controller mappings

If for your controller is misconfigured by the automatic system, you may want to look at the RetroArch log. The log will show if a profile has been selected for your controller, and the path of the selected profile.