Ensure the bluetooth controller is not blocked. Use rfkill to check whether there are any blocks and to remove soft blocks. If there is a hard block, there is likely either a physical hardware switch or an option in the BIOS to enable the bluetooth controller.

$ rfkill
0 wlan      phy0   unblocked unblocked
1 bluetooth hci0     blocked unblocked

# rfkill unblock bluetooth


Install the bluez package.

# xbps-install -S bluez

Enable the bluetoothd and dbus services.

# ln -s /etc/sv/dbus /var/service
# ln -s /etc/sv/bluetoothd /var/service

Add your user to the bluetooth group and restart the dbus service, or simply reboot the system. Note that restarting the dbus service may kill processes making use of it.

# usermod -a -G bluetooth $USER
# sv restart dbus

Note: To use an audio device such as a wireless speaker or headset, ALSA users need to install the bluez-alsa package, while PulseAudio users do not need any additional software.


Manage bluetooth connections and controllers using bluetoothctl. It uses a command line interface; to find out what commands are available, enter help. To exit, enter exit or quit.

$ bluetoothctl

[bluetooth]# help
Menu main:
Available commands:
advertise             Advertise Options Submenu
scan                  Scan Options Submenu
gatt                  Generic Attribute Submenu
list                  List available controllers
show [ctrl]           Controller information
select <ctrl>         Select default controller
devices               List available devices
paired-devices        List paired devices

Consult the Arch Wiki page for an example on how to pair a device.

bluetoothctl also accepts taking commands from stdin.

$ echo "devices" | bluetoothctl
Agent registered
[bluetooth]# devices
Device XX:XX:XX:XX:XX:XX Mouse
Device XX:XX:XX:XX:XX:XX Keyboard
Device XX:XX:XX:XX:XX:XX Speaker
Device XX:XX:XX:XX:XX:XX Headset


The main configuration file is /etc/bluetooth/main.conf.