Configure Bluetooth on Fedora
You try to pair your headphones and the terminal spits out No default controller available. You check the GNOME settings and the toggle is grayed out. You've rebooted. You've toggled the physical switch on the laptop chassis. The radio is silent. Or the device pairs, connects, and then drops the audio stream after ten seconds of silence. Bluetooth on Linux is rarely just plug and play when the stack is misconfigured, the firmware is missing, or the kernel has blocked the adapter.
How the stack works
Fedora uses BlueZ as the Bluetooth protocol stack. BlueZ implements the Bluetooth Core Specification and runs as a system daemon. It exposes D-Bus interfaces that applications use to control the radio and manage devices. bluetoothctl is a command-line D-Bus client. GNOME Settings is a graphical D-Bus client. If BlueZ is not running, or if the kernel cannot communicate with the hardware adapter, no client will work.
The hardware adapter itself is subject to kernel-level controls. rfkill manages radio frequency kill switches. A soft block is a software flag set by the OS or a driver. A hard block is a physical switch or firmware state. The kernel respects hard blocks over soft blocks. If the adapter is blocked, the device disappears from the system entirely.
Audio devices add a second layer. BlueZ handles the connection and the baseband protocol. PipeWire handles the audio stream. PipeWire requires specific plugins to decode Bluetooth audio profiles like A2DP for playback or HSP/HFP for headsets. If the plugins are missing, the device connects but produces no sound.
Check rfkill list before blaming the driver. A soft block is the most common reason the adapter disappears.
Install and enable the service
Here's how to ensure the BlueZ stack is installed and the service is active. Fedora Workstation includes BlueZ by default. Minimal installs or server configurations often require manual installation.
sudo dnf install -y bluez bluez-tools
# bluez provides the daemon and core libraries. bluez-tools adds legacy utilities like hciconfig.
sudo systemctl enable --now bluetooth
# enable ensures the service starts on boot. --now starts it immediately in the current session.
Verify the daemon is running and the adapter is recognized by the kernel.
systemctl status bluetooth
# Check for active (running) state. Look for recent errors in the log output below the status line.
rfkill list bluetooth
# rfkill shows hardware and software blocks. If 'Soft blocked: yes', the OS has disabled the radio.
If rfkill reports a soft block, clear it to allow the radio to transmit.
sudo rfkill unblock bluetooth
# unblock removes the software block. The hardware block must be cleared via a physical switch or Fn key.
Run systemctl status before restarting. The status output includes recent journal lines that often explain why a service failed to start.
Pair devices with bluetoothctl
Use bluetoothctl to pair devices when the GUI is unavailable or when you need precise control over the pairing process. The interactive shell gives you immediate feedback on scan results and pairing states.
bluetoothctl
# Enter the interactive BlueZ control shell.
[bluetooth]# power on
# Turn on the local Bluetooth controller.
[bluetooth]# agent on
# Enable the agent to handle pairing requests and PIN entry.
[bluetooth]# default-agent
# Register this agent as the default handler for all pairing events.
[bluetooth]# scan on
# Start scanning for nearby devices. Output shows MAC addresses and names.
[bluetooth]# pair AA:BB:CC:DD:EE:FF
# Initiate pairing with the target device. Follow prompts for PIN or passkey.
[bluetooth]# trust AA:BB:CC:DD:EE:FF
# Mark the device as trusted so it auto-connects when in range.
[bluetooth]# connect AA:BB:CC:DD:EE:FF
# Establish the active connection.
[bluetooth]# quit
# Exit the interactive shell.
Run single commands without entering the interactive shell for scripting or quick checks.
bluetoothctl list
# List available controllers. Useful if you have multiple adapters.
bluetoothctl devices
# Show paired and trusted devices.
Trust the device after pairing. Without trust, the connection drops every time the daemon restarts.
Audio and PipeWire
Audio devices require PipeWire plugins to handle Bluetooth codecs like A2DP and HSP/HFP. Fedora uses PipeWire as the default audio server. The core Bluetooth backend is separate from the main PipeWire package.
sudo dnf install pipewire-codec-aptx libspa-0.2-bluetooth
# libspa-0.2-bluetooth provides the core Bluetooth audio backend for PipeWire.
# pipewire-codec-aptx adds support for high-quality audio codecs if your hardware supports them.
systemctl --user restart pipewire pipewire-pulse
# Restart the user session services to load the new plugins.
Confirm the device is connected and audio is routing correctly.
bluetoothctl info AA:BB:CC:DD:EE:FF
# Check 'Connected: yes' and 'Trusted: yes' in the output.
pactl list short sinks
# List audio sinks. Look for the Bluetooth device in the output.
Restart PipeWire as the user, not root. Audio services run in the user session and root cannot manage them.
Troubleshooting common failures
Inspect the daemon logs to identify why a device fails to pair or the service crashes.
journalctl -xeu bluetooth
# -x adds explanatory text. -e jumps to the end. -u filters by unit.
# Look for 'Failed to set scan parameters' or 'Connection refused'.
The error No default controller available usually means the kernel driver failed to probe the adapter. Check dmesg for hardware errors.
dmesg | grep -i bluetooth
# Look for firmware load failures or probe errors.
lsusb | grep -i bluetooth
# Verify USB adapters are detected by the kernel.
lspci | grep -i bluetooth
# Verify PCIe adapters are detected by the kernel.
Missing firmware is a common cause of probe failures. Install the appropriate firmware package based on the error in dmesg.
sudo dnf install iwlwifi-mvm-firmware
# Install firmware for Intel combo cards if dmesg reports missing firmware.
sudo dnf install linux-firmware
# Install the main firmware bundle if multiple devices report missing firmware.
Audio devices may drop the stream or switch to low-quality mode. Bluetooth audio uses profiles. A2DP is for high-quality playback. HSP/HFP is for headsets with microphones. Switching profiles can cause dropouts. Force the profile if the device behaves incorrectly.
bluetoothctl select-profile AA:BB:CC:DD:EE:FF a2dp
# Force A2DP profile for high-quality audio playback.
bluetoothctl select-profile AA:BB:CC:DD:EE:FF hsp
# Force HSP profile for headset mode with microphone support.
NetworkManager can manage Bluetooth network connections like PAN or NAP. This is distinct from audio or HID devices. If you are setting up a Bluetooth network, ensure NetworkManager has the Bluetooth plugin.
sudo dnf install NetworkManager-bluetooth
# Install the NetworkManager plugin for Bluetooth network management.
sudo systemctl restart NetworkManager
# Restart NetworkManager to load the plugin.
Read dmesg for firmware errors. Missing firmware is the silent killer of Bluetooth adapters.
When to use each tool
Use GNOME Settings when you are pairing standard peripherals like mice, keyboards, or headphones on a desktop session.
Use bluetoothctl when you are on a minimal server install, a TTY console, or need to script device management.
Use rfkill unblock when the adapter is soft-blocked by the kernel and the software toggle is grayed out.
Use pipewire packages when audio devices connect but produce no sound or drop the stream.
Use dmesg and firmware packages when the kernel reports probe failures or missing firmware for the adapter.
Use journalctl -xeu bluetooth when the daemon crashes or devices fail to pair without a clear error.
Stay on the default BlueZ configuration unless you are running a custom stack or need specific low-level debugging.