From NixOS Wiki
Jump to: navigation, search

Enabling Bluetooth support

To enable support for Bluetooth devices, add hardware.bluetooth.enable to /etc/nixos/configuration.nix:

  hardware.bluetooth.enable = true;

Pairing Bluetooth devices

In order to use Bluetooth devices, they must be paired with your NixOS machine. Heavier desktop environments will usually provide a Bluetooth management GUI which you can use to pair devices.

If your desktop environment does not provide such a GUI, you can additionally enable the blueman service, which provides blueman-applet and blueman-manager with the snippet below.

services.blueman.enable = true;

Pairing devices from the command line

Alternatively, Bluetooth devices can be paired from the command line using bluetoothctl.

$ bluetoothctl
[bluetooth] # power on
[bluetooth] # agent on
[bluetooth] # default-agent
[bluetooth] # scan on
...put device in pairing mode and wait [hex-address] to appear here...
[bluetooth] # pair [hex-address]
[bluetooth] # connect [hex-address]

Bluetooth devices automatically connect with bluetoothctl as well:

$ bluetoothctl
[bluetooth] # trust [hex-address]

Using Bluetooth headsets with PulseAudio

To allow Bluetooth audio devices to be used with PulseAudio, amend /etc/nixos/configuration.nix as follows:

  hardware.pulseaudio = {
    enable = true;

    # NixOS allows either a lightweight build (default) or full build of PulseAudio to be installed.
    # Only the full build has Bluetooth support, so it must be selected here.
    package = pkgs.pulseaudioFull;

  hardware.bluetooth.enable = true;

You will need to restart PulseAudio; try systemctl --user daemon-reload; systemctl --user restart pulseaudio.

You can verify that PulseAudio has loaded the Bluetooth module by running pactl list | grep -i 'Name.*module.*blue'; Bluetooth modules should be present in the list.

System-Wide PulseAudio

When you are running PulseAudio system-wide then you will need to add the following modules to your configuration:

hardware.pulseaudio.configFile = pkgs.writeText "" ''
  load-module module-bluetooth-policy
  load-module module-bluetooth-discover
  ## module fails to load with 
  ##   module-bluez5-device.c: Failed to get device path from module arguments
  ##   module.c: Failed to load module "module-bluez5-device" (argument: ""): initialization failed.
  # load-module module-bluez5-device
  # load-module module-bluez5-discover

Enabling extra codecs

WARNING: The hardware.pulseaudio.extraModules option is only available in the 19.03 release or later.

While pulseaudio itself only has support for the SBC bluetooth codec there is out-of-tree support for AAC, APTX, APTX-HD and LDAC.

To enable extra codecs add the following to /etc/nixos/configuration.nix:

  hardware.pulseaudio = {
    enable = true;
    extraModules = [ pkgs.pulseaudio-modules-bt ];
    package = pkgs.pulseaudioFull;

Enabling A2DP Sink

Modern headsets will generally try to connect using the A2DP profile. To enable this for your bluetooth connection, add the following to /etc/nixos/configuration.nix

hardware.bluetooth.extraConfig = "

This configuration may be unnecessary and does not work with bluez5 (Unknown key Enable for group General ).

Note: Using gdm as the display manager can cause failures to connect to A2DP Sink.

Managing audio devices

pavucontrol can be used to reconfigure the device:

  • To enable A2DP, change the profile to “High Fidelity Playback (A2DP Sink)” on the “Configuration” tab.
  • To set the device as the default audio output, select “set as fallback” on the “Output Devices” tab.

Alternatively, the device can be configured via the command line:

  • To enable A2DP, run:
    $ pacmd set-card-profile "$(pactl list cards short | egrep -o bluez_card[[:alnum:]._]+)" a2dp_sink
  • To set the device as the default audio output, run:
    $ pacmd set-default-sink "$(pactl list sinks short | egrep -o bluez_sink[[:alnum:]._]+)"


USB device needs to be unplugged/re-plugged after suspend

Some USB device/host combinations don't play well with the suspend/resume cycle, and need to be unplugged and then re-plugged to work again.

It is possible to simulate a unplug/re-plug cycle using the /sys filesystem.

This gist provides a script and instructions to set-up a workaround for these devices.

When connecting to an audio device: Failed to connect: org.bluez.Error.Failed

You need to use pulseaudioFull, see #Using Bluetooth headsets with PulseAudio.

Bluetooth fails to power on with Failed to set power on: org.bluez.Error.Blocked

If journalctl -eu bluetooth shows Failed to set mode: Blocked through rfkill (0x12), rfkill might be blocking it:

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

Unblock it first:

$ sudo rfkill unblock bluetooth

Cannot use bluetooth while it previously worked


  • When using bluetoothctl, getting "No agent is registered".
  • When using blueman or anything using dbus to talk to bluez, getting dbus.exceptions.DBusException: org.freedesktop.DBus.Error.AccessDenied: Rejected send message"

This possibly can be fixed by restarting the display-manager session. The session management may have had an issue with registering your current session and doesn't allow you to control bluetooth.

sudo systemctl restart display-manager.service

See also