How to Use Bluetooth on Raspberry Pi: GUI & Command Guide

More and more devices today can use Bluetooth, and interestingly, it’s not that complicated to pair these Bluetooth devices with a Raspberry Pi (even without a desktop environment). So, if you have a Bluetooth mouse or speaker you’d like to use with your Pi, keep reading, and I’ll show you everything.

On Raspberry Pi OS with Desktop, there’s a graphical tool to configure Bluetooth devices in the top-right corner, and most distributions will have similar options. From the command line, the “bluetoothctl” utility can be used to scan, pair, and configure Bluetooth devices.

Let’s start with a desktop environment, using the tool on Raspberry Pi OS with Desktop, and I’ll then give you the commands to do it from a terminal (or Lite edition). I’ll finish with a few examples of Bluetooth devices you can use to enhance your Pi experience.

If you’re looking to quickly progress on Raspberry Pi, you can check out my e-book here. It’s a 30-day challenge where you learn one new thing every day until you become a Raspberry Pi expert. The first third of the book teaches you the basics, but the following chapters include projects you can try on your own.

Set up Bluetooth with the GUI

If you use the default Raspberry Pi OS desktop environment (PiXeL), there’s a Bluetooth icon in the top-right corner next to the clock. This utility can be used to enable or disable the Bluetooth adapter and pair new devices.

Turn On Bluetooth

By default, Bluetooth is enabled on a fresh installation of Raspberry Pi OS with Desktop, so you can probably skip this step.

But if for some reason the Bluetooth is disabled on your Pi (grayed out), click on it and select “Turn On Bluetooth” from the dropdown menu. It looks like this:

Bluetooth is now enabled, and you can move on to pairing your Bluetooth devices.

Pair a New Device

The Raspberry Pi will only detect Bluetooth devices set to pairing mode. Refer to your device’s user guide to learn how to do this. Generally, there’s a Bluetooth button on it that you need to press once or hold down for a few seconds to make it discoverable.

Some devices can’t be paired to more than one device, so you may need to disconnect it from your other computer, for example. As it’s different with all accessories, it’s better to check the official documentation.

Here’s how you can start the Bluetooth pairing process on Raspberry Pi OS Desktop:

• Click on the Bluetooth icon in the top-right corner.
• Click on “Add device…”
• The Raspberry Pi will start listing all detected devices in a window. It should look like this:
  
• Click on the device you want, then click the “Pair” button.
• A few seconds later, you’ll get a confirmation that the pairing was successful:
  
• After pairing, you may need to open the Bluetooth menu again and click “Connect” from the device menu to finalize the connection.

Once the device is connected, there might be additional steps to configure it. This will depend on the type of device. I’ll give you more details at the end of this article (Bluetooth usage examples).

For example, a mouse or keyboard might work immediately, while a speaker or phone will require additional steps to configure.

Unpair a Connected Device

Once a device is paired with the Raspberry Pi, it will be listed in the dropdown menu when you click on the Bluetooth icon. You can find at least two actions in this menu: disconnect (temporarily) and remove (forget this device and unpair completely).

For audio devices in particular, you may be interested in this article if it doesn’t work right away: How To Fix Sound Issues On Raspberry Pi: Easy Solutions.

Set up Bluetooth using the terminal

Whether you use SSH, a Linux distribution without a GUI like Raspberry Pi OS Lite, or a simple terminal, it’s possible to achieve the same result from the command line.

On the command line, the main tool is the “bluetoothctl” utility. It opens a text prompt where you can type specific actions to manage everything related to your Bluetooth adapter and devices.

Turn On Bluetooth From the Command Line

Even on Raspberry Pi OS Lite, Bluetooth is enabled by default on a fresh installation. I’ll give you the instructions just in case you use another distribution or have it disabled, but in theory, you won’t have to do this:

• Make sure bluetooth isn’t blocked by default:
  rfkill unblock bluetooth
• Start the bluetoothctl utility:
  bluetoothctl
• Enable:
  power on
• And to close the tool:
  exit
  You’ll most likely continue with the pairing procedure first, but at least you know how to quit :-).

That’s it, Bluetooth is enabled, and you can move to the next step.

Are you a bit lost in the Linux command line? Check this article first for the most important commands to remember and a free downloadable cheat sheet so you can have the commands at your fingertips.

Pair a New Bluetooth Device From the Terminal

Theory

This procedure has almost the same steps as with a GUI:

• Put the device in pairing mode.
• Search for devices.
• Pair with the one you want to associate with.
• Connect to it if you want to use it directly.
  This step is automatic with a GUI, but there is an extra command in a terminal.

As mentioned earlier, we’ll do everything with the bluetoothctl utility. There are many commands, but luckily they are pretty intuitive (with logical names and not that many options).

Here are the most important commands to know:

• power on – Turns on Bluetooth.
• power off – Turns off Bluetooth.
• scan on – Starts scanning for Bluetooth devices.
• scan off – Stops scanning for Bluetooth devices.
• pair <address> – Pairs with a Bluetooth device.
• remove <address> – Unpair a Bluetooth device.
• connect <address> – Connects to a Bluetooth device.
• disconnect <address> – Disconnects from a Bluetooth device.
• devices – List paired devices.

Use help to see all the options available, but these commands should be enough in most cases.

Example

Let’s take a concrete example. I have a Bluetooth keyboard I want to pair with on Raspberry Pi OS Lite (I’m doing this via SSH for my comfort, but it doesn’t change anything).

Here are the main steps to pair a keyboard to Raspberry Pi OS Lite:

• Put the device in pairing mode.
  On my keyboard, there is a Bluetooth button on the back:
  
• Start the “bluetoothctl” tool:
  bluetoothctl

• Start a scan to list all devices nearby:
  scan on

  You’ll start to see all devices with their address (in pink on my screenshot) listed on your screen.
• Find the device you want to associate (the last one for me) and use the pair command to pair it with the Raspberry Pi:
  pair <address>

  A bunch of debug lines will show up, but the important ones are in the end “Pairing: yes” and especially “Pairing successful”.
• In most cases, you’ll also need to connect to it once the pairing is completed.
  Same syntax with the “connect” command:
  connect <address>


That’s it—my keyboard works immediately, and I didn’t have to take any extra steps to configure it. But as mentioned earlier, depending on the type of device, additional configuration might be required (changing the default audio output for example).

Bluetooth Usage Examples on Raspberry Pi

You now know how to pair any Bluetooth device with your Raspberry Pi. Now here are a few ideas on how you can use Bluetooth devices to improve your experience with your Pi.

Audio

I’m a bit picky about sound quality, and I can’t bear the sound from the monitor’s speakers when I listen to music, so I don’t use the HDMI output for sound. You can plug fancy speakers into the audio jack, but I generally find using Bluetooth speakers to be the easiest way.

I tried it with two of my Bluetooth speakers, and it worked pretty well, so I recommend giving it a try, especially if you use your Pi for desktop usage, media center or as a Spotify player.

There’s an extra step after pairing the speaker, you need to click on the sound icon and choose the new device in the dropdown menu. It looks like this:

You can then go to “Device Profiles” to adjust the settings if needed (volume, etc.), but it isn’t mandatory.

If you don’t have a GUI, it’s the same thing, but remember that some dependencies may be required (ex: audio packages to use a Bluetooth speaker).

Mouse/Keyboard

Another great way to take advantage of the Bluetooth feature is to use a wireless mouse and keyboard with your Raspberry Pi. In my comparisons of the best keyboards for Raspberry Pi, I had a great one that works via USB or Bluetooth (so you can still do the installation with the cable).

I tested it for this article, and it worked perfectly. Just press the Bluetooth button and follow the instructions given above.

If needed, you can then go to “Preferences” > “Mouse & keyboard settings” to configure advanced options (mouse speed, for example).

Game Controller

If you are into retro-gaming and play Retropie on your Raspberry Pi, keep in mind that it’s definitely possible to use a wireless controller with it, even in Bluetooth mode (like PS4 controllers).

I have several tutorials about this on this website, I’ll let you check them out for more details if you’re interested:

• How to Use a PS4 controller on Retropie? (The Easy Way)
• How to Pair PS4 Controller with Recalbox? (Bluetooth)
• How to Connect a Bluetooth Controller to Lakka? (Really Works)

Connect to the Pi From Another Computer

Note: If for any reason you need to connect to your Raspberry Pi from another device, you need to make it discoverable first. And you’ll probably have to use a PIN code to confirm the connection.

From the command line, you’ll enter the bluetoothctl utility like before:
discoverable on


You also have the option from the desktop interface (“Make discoverable” in the dropdown menu when you click the Bluetooth icon):

I connected it to my laptop, but I didn’t have much success in terms of applications I could use with this connection, so I don’t know how useful this can be. In theory, I guess you should be able to transfer files, but it didn’t work for me.

Until next time, experience the joys of Bluetooth bliss with your Raspberry Pi.

Whenever you’re ready, here are other ways I can help you:

The RaspberryTips Community: If you want to hang out with me and other Raspberry Pi fans, you can join the community. I share exclusive tutorials and behind-the-scenes content there. Premium members can also visit the website without ads.

Master your Raspberry Pi in 30 days: If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.

The Raspberry Pi Bootcamp: Understand everything about the Raspberry Pi, stop searching for help all the time, and finally enjoy completing your projects.

Master Python on Raspberry Pi: Create, understand, and improve any Python script for your Raspberry Pi. Learn the essentials step-by-step without losing time understanding useless concepts.

You can also find all my recommendations for tools and hardware on this page.