Configuring Bluetooth on Linux

The Bluetooth Blues


Getting Bluetooth and PulseAudio to play nicely takes a little work. Bruce walks you through the basics of getting Bluetooth up and running on Linux.

Getting Bluetooth sound to work always reminds me of the bad old days when configuring every piece of hardware to function with Linux was a struggle. To be fair, part of the trouble is PulseAudio, Linux’s sound system, which can be a cantankerous application in its own right and does not play particularly well with Bluetooth, often ceasing to coordinate with the least change. Still another challenge is finding relevant online help. However, the stereo-quality sound of high-end Bluetooth speakers makes the struggle worth any audiophile’s time. What follows is some of the basics, most of which applies to other Bluetooth devices as well.

Before configuring Bluetooth support, update your PulseAudio installation and check that it is still working. At least in theory, this precaution can help you pinpoint where any problems lie. In addition, install or update the following packages: bluetooth, pulseaudio-module-bluetooth, and pavucontrol, the GUI for configuring PulseAudio. To check that Bluetooth support is enabled, run:

systemctl status bluetooth

You may need to reboot before your system is ready or to stop and restart Bluetooth and PulseAudio using systemctl (Figure 1). For instance, to start Bluetooth, use the command:

systemctl start bluetooth
Figure1: Bluetooth up and operating with music playing.

If Bluetooth is not running, you can buy a USB dongle for $5-40, depending on quality, range, energy consumption, and version. Low energy consumption dongles may have a limited range of a couple of meters, so the positioning of your speaker may affect your purchase. Most dongles support Bluetooth 4.0, and many will support earlier versions. Most, too, should support Linux out of the shrink wrap.


To set up a speaker, you must pair it with your computer’s Bluetooth support, linking the two. To save time, you can also set your speaker as trusted, so it pairs automatically each time it is turned on, saving you time and repetition. Depending on the software you use, your computer can be identified as the controller or adapter, while the speaker device, for some arcane reason, is sometimes referred to as a headphone.

You can use a variety of desktop tools for configuration, including the tools provided by Gnome and KDE, or install blueman. However, I recommend bluetoothctl for configuration (Figure 2), a command-line tool that breaks down tasks into smaller steps, so you can see where the problem lies (Figure 3). bluetoothctl consists of the basic command, plus a sub-command, and, in places the device or controller ID. For instance, the command

bluetoothctl select F4-F5-D8-E7-B5-AD

sets the controller to the one with that ID. You could also use a user-friendly alias, if you have given the controller one:

bluetoothctrl select Nanday
Figure 2: List basic sub-commands with bluetoothctl help.
Figure 3: The advantage of bluetoothctl list is that it gives detailed information about what it is doing.

The first step is to prepare the controller. Use the sub-commands list or show to learn the controller’s ID or copy it from a desktop tool. Then use discoverable to get the speaker’s ID. To pair, consult the speaker’s manual about how to prepare it for pairing. (In the case of my speaker, that consists of holding down the plus volume control at the same time as pressing a small button by the on button. Your speaker may have another method. Usually, an audio cue tells you that the speaker is ready.) The speaker will be pairable for about two minutes. If you fail to pair the first time, one reason may be that you started the attempt to pair with too little time left to establish the connection. Pairing may also be erratic for other reasons, so you may need several tries before you are successful.

Returning to the speaker, use the sub-command pairable on, quickly followed by pair SPEAKER-ID. When a pairing is successful, another audio cue is given, but use paired devices to check. Finish with trust SPEAKER-ID so that the speaker is automatically paired when turned on, and your speaker is ready for use. You will want your speaker to be trusted, because, unlike wired speakers, your Bluetooth speaker runs on batteries, and you probably do not want to have it on all the time. As a last step for security’s sake, run discoverable off so your controller does not become a back door to your entire system.

At this point, open pavucontrol and go to the Configuration tab (Figure 4). The tab should show your speaker, but sometimes it will not be turned on. The most likely setting you need will be High Fidelity Playback (A2DP Sink), which gives the highest quality sound. Should you have trouble with a particular application, start it and find it on pavucontrol’s Playblack tab (Figure 5). From here, you can adjust volume, set the output to your Bluetooth speaker, or reset the volume.

Figure 4: A UE Boom 2 speaker running properly on pavucontrol.
Figure 5: The Clementine music player up and functioning on pavucontrol.

In KDE’s Plasma, you can also use Phonon to choose which output source to use for which purpose, such as for video games or accessibility, in case that matters to your purposes. Phonon has been de-emphasized in recent Plasma releases. If you have only the one speaker, it will be listed as simply PulseAudio Sound Speaker. Still, check that it has been applied to all the categories you need -- you might get a burst of sound from a few clicks (Figure 6).

Figure 6: Plasma’s Phonon can set different outputs for different functions, which can sometimes result in no sound.

The processes of pairing and setting a device to trusted are simplest when the speaker is the only Bluetooth device. In some cases, you may want to use the block or unconnect sub-command to temporarily conceal another Bluetooth device to avoid confusion, restoring it later with unblock or connect. You might also use these sub-commands along with untrust when a Bluetooth device reaches the end of its usefulness.

Advanced Troubleshooting

Unfortunately, both Bluetooth and PulseAudio are erratic enough that the process is not always straightforward. It is all too common that a system that has been working perfectly before it stops working for no obvious reason. The problem can be as simple as PulseAudio not turning on a perfectly installed speaker, which can be quickly fixed in pavucontrol. Or perhaps a file in ~./.config/pulse, left there after a previous installation, is not compatible with an upgrade or the files in /etc/pulse. If editing or deleting some of these files does nothing, a host of other solutions are identified on the Debian and Arch Bluetooth wikis.

Sometimes, coaxing Bluetooth and PulseAudio to get along can make me wonder if the effort is worth my time. However, music to work by matters to me. When I find myself in the middle of yet another temporary breakdown of sound for no apparent reason, I remind myself that two decades ago, similar problems frequently happened with printers, scanners, and even keyboards and mouses. Surely there’s a less painful means to stay in touch with my Linux roots.

Related content

  • Adding a Bluetooth Speaker to Linux
  • Pi OS 2020-12-02

    The Raspberry Pi Foundation regularly adds new features to the official operating system, Raspberry Pi OS. The December 2020 update added the PulseAudio sound server and a print manager.

  • PipeWire

    In the coming year, PipeWire will replace PulseAudio, resulting in better audio on Linux. If you can't wait, here's what you need to know to get started with PipeWire.

  • PulseEffects

    A wildly flashing equalizer once was part of the basic equipment of every decent stereo system. PulseEffects upgrades the PulseAudio server to include these slide controls – and offers even more.

  • Sound Studio Workshop

    Once you get your podcast operation up and running, you might decide you want a real mixer and some higher-end software. We'll introduce you to Ardour and get you started with some basic audio hardware.

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More