Skip to content

Linux Bluetooth Configuration

Jump to bottom
Mattscreative edited this page Dec 5, 2025 · 2 revisions

Linux Bluetooth Configuration Guide

Complete beginner-friendly guide to configuring Bluetooth on Linux, covering Arch Linux, CachyOS, and other distributions including device pairing, audio setup, and troubleshooting.

Table of Contents

  1. Understanding Bluetooth
  2. Installing Bluetooth
  3. Pairing Devices
  4. Bluetooth Audio
  5. Troubleshooting

Understanding Bluetooth

What is Bluetooth?

Bluetooth is wireless technology for short-range communication.

What it does:

  • Connect devices: Wireless device connection
  • Audio: Bluetooth headphones, speakers
  • Input devices: Keyboards, mice
  • File transfer: Transfer files between devices

Why configure:

  • Wireless freedom: No cables needed
  • Convenience: Easy device connection
  • Audio: Wireless audio devices
  • Productivity: Wireless input devices

Installing Bluetooth

Install Bluetooth Stack

Arch Linux / CachyOS:

# Install BlueZ
sudo pacman -S bluez bluez-utils

# Enable and start service
sudo systemctl enable --now bluetooth.service

Debian/Ubuntu:

sudo apt install bluez bluez-tools
sudo systemctl enable --now bluetooth

Fedora:

sudo dnf install bluez bluez-tools
sudo systemctl enable --now bluetooth

GUI Tools

Install GUI manager:

# Install Blueman (Arch/CachyOS)
sudo pacman -S blueman

# Launch
blueman-manager

Other distributions:

# Debian/Ubuntu
sudo apt install blueman

# Fedora
sudo dnf install blueman

Pairing Devices

Using bluetoothctl

Pair device:

# Start bluetoothctl
bluetoothctl

# Power on
power on

# Scan for devices
scan on

# Pair with device
pair MAC-ADDRESS

# Connect
connect MAC-ADDRESS

# Trust device (auto-connect)
trust MAC-ADDRESS

# Exit
quit

Explanation:

  • power on: Turns on Bluetooth adapter
  • scan on: Scans for nearby devices
  • pair: Pairs with device (may require PIN)
  • connect: Connects to paired device
  • trust: Allows auto-connection

Using GUI (Blueman)

Pair with GUI:

  1. Open Blueman:

    blueman-manager

  2. Click "Search" to scan for devices

  3. Select device from list

  4. Click "Pair" and enter PIN if required

  5. Device should connect automatically

Bluetooth Audio

PulseAudio

Configure PulseAudio for Bluetooth:

# Install Bluetooth support
sudo pacman -S pulseaudio-bluetooth

# Restart PulseAudio
pulseaudio -k && pulseaudio --start

Or enable service:

systemctl --user restart pulseaudio

PipeWire

PipeWire includes Bluetooth support:

# PipeWire has built-in Bluetooth support
# No additional package needed

# Restart PipeWire if needed
systemctl --user restart pipewire pipewire-pulse

Connect Audio Device

After pairing:

  1. Open audio settings (pavucontrol or system settings)

  2. Select Bluetooth device as output

  3. Test audio by playing sound

Troubleshooting

Bluetooth Not Working

Check service:

# Check Bluetooth status
sudo systemctl status bluetooth

# Restart if needed
sudo systemctl restart bluetooth

Device Not Found

Check adapter:

# Check if adapter is on
bluetoothctl show

# Power on if off
bluetoothctl power on

Connection Issues

Reset Bluetooth:

# Restart Bluetooth
sudo systemctl restart bluetooth

# Remove device
bluetoothctl remove MAC-ADDRESS

# Re-pair
bluetoothctl pair MAC-ADDRESS

Audio Not Working

Check audio:

# Check if device connected
bluetoothctl devices

# Check audio sink
pactl list sinks short

# Set as default
pactl set-default-sink bluetooth-sink-name

Summary

This guide covered Bluetooth configuration for Arch Linux, CachyOS, and other distributions, including installation, pairing, audio setup, and troubleshooting.

Next Steps

This guide covers Arch Linux, CachyOS, and other Linux distributions. For distribution-specific details, refer to your distribution's documentation.

Clone this wiki locally