How to Set Up Bluetooth on Linux

Bluetooth on Linux has improved enormously over the past few years. The BlueZ stack is mature, PipeWire handles audio profiles cleanly, and most devices pair first try. That said, you still need to know which pieces to install, which service to enable, and where to look when something goes wrong. This guide walks you through the full setup: installing BlueZ, pairing a device from both the command line and a GUI, getting audio working, and fixing the issues that actually come up.

Install BlueZ and Supporting Tools

BlueZ is the official Linux Bluetooth stack. Most desktop installs include it, but a minimal or server install may not. Install the daemon, the command-line client, and a GUI front-end for desktop use.

Debian / Ubuntu

sudo apt update
sudo apt install bluez bluetooth blueman

Fedora / RHEL 9+ / Rocky Linux

sudo dnf install bluez blueman

Arch Linux

sudo pacman -S bluez bluez-utils blueman

blueman is a solid GTK-based Bluetooth manager that works on both X11 and Wayland sessions. GNOME users can skip it and use the built-in Settings panel instead; KDE users have their own Bluetooth widget in System Settings.

Enable and Start the Bluetooth Service

BlueZ runs as a systemd service called bluetooth. Enable it so it starts on boot, then start it immediately.

sudo systemctl enable --now bluetooth

Confirm it is running:

systemctl status bluetooth

You should see active (running) in the output. If the service fails to start, check journalctl -u bluetooth -b for errors — missing firmware is the most common cause on laptops.

Verify Your Bluetooth Adapter is Detected

Before pairing anything, confirm the kernel sees your adapter.

hciconfig -a

Or with the newer tool:

bluetoothctl show

You should see a controller listed with its MAC address. If nothing appears, your adapter may need firmware — see the Troubleshooting section below.

Pair a Device Using bluetoothctl

bluetoothctl is an interactive shell included with BlueZ. It is the most reliable way to pair any device and works over SSH without a display.

bluetoothctl

Inside the interactive prompt, run these commands in order:

power on
agent on
default-agent
scan on

Put your Bluetooth device in pairing mode. Within a few seconds you will see its MAC address printed, for example [NEW] Device AA:BB:CC:DD:EE:FF JBL Flip 6. Copy the MAC address, then:

pair AA:BB:CC:DD:EE:FF
trust AA:BB:CC:DD:EE:FF
connect AA:BB:CC:DD:EE:FF
scan off
quit

trust tells BlueZ to reconnect to this device automatically in future sessions. Without it, the device will need manual connection after every reboot.

Pair a Device Using a GUI

If you installed blueman, launch the Bluetooth Manager from your application menu or run:

blueman-manager &

Click Search, put your device in pairing mode, and double-click it when it appears. Follow any PIN prompt. GNOME users go to Settings → Bluetooth and click the device name. KDE users open System Settings → Bluetooth.

The applet also places a tray icon (blueman-applet) for quick connect/disconnect. Add it to your autostart if you use it regularly.

Set Up Bluetooth Audio

Modern Linux desktops use PipeWire with pipewire-pulse as the audio layer. If your system is running PipeWire (Ubuntu 22.04+, Fedora 34+, Arch), Bluetooth audio profiles — A2DP for stereo playback, HFP/HSP for headset mode with a microphone — are handled automatically once the device is connected.

Check PipeWire is Running

systemctl --user status pipewire pipewire-pulse

Switch Audio Profiles

If your headset connects in HSP/HFP mode (call quality, lower fidelity) instead of A2DP (high-quality stereo), switch it manually. With PipeWire this is easiest from the sound settings in your desktop, but you can also use wpctl:

wpctl status

Find the sink for your headset, then switch to A2DP through your desktop's sound panel (Output tab in GNOME Sound Settings, or right-click the tray volume icon on KDE and choose the A2DP profile).

Legacy PulseAudio Systems

If you are on an older system still running PulseAudio, install the Bluetooth module:

sudo apt install pulseaudio-module-bluetooth
pulseaudio -k

PulseAudio will restart automatically and pick up the module. Switch profiles with pactl or pavucontrol.

Verify the Connection

List connected devices:

bluetoothctl devices Connected

For audio, open your desktop's sound settings and confirm the Bluetooth device appears as an output. Play audio and confirm it routes to the headset or speaker. For input devices like keyboards and mice, just try typing or moving the pointer.

Troubleshooting

Adapter Not Found After Boot

Many Intel and Realtek Bluetooth chips need firmware loaded at boot. On Debian/Ubuntu:

sudo apt install firmware-linux firmware-linux-nonfree
sudo reboot

On Arch, install linux-firmware (usually already present). Check dmesg | grep -i bluetooth for firmware load errors.

Device Pairs But Disconnects Immediately

This is almost always a power management issue. Disable USB autosuspend for the Bluetooth adapter:

echo 'ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="", ATTR{power/autosuspend}="-1"' | sudo tee /etc/udev/rules.d/50-bluetooth-pm.rules
sudo udevadm control --reload-rules

Find your vendor ID with lsusb. Alternatively, add btusb module options in /etc/modprobe.d/btusb.conf:

echo 'options btusb enable_autosuspend=n' | sudo tee /etc/modprobe.d/btusb.conf

No Sound Despite A2DP Profile Selected

Restart PipeWire as your user — do not use sudo:

systemctl --user restart pipewire pipewire-pulse wireplumber

If the problem persists, check that libspa-0.2-bluetooth (Debian/Ubuntu) or pipewire-codec-aptx (optional, Fedora) is installed.

# Debian/Ubuntu
sudo apt install libspa-0.2-bluetooth

# Arch
sudo pacman -S pipewire-audio

Device Won't Re-Pair After Kernel Update

Remove the device from BlueZ's database and re-pair from scratch:

bluetoothctl remove AA:BB:CC:DD:EE:FF

Then pair again as described above. Also clear the pairing on the device side (put it back into pairing mode) before retrying.