How To Run Bluetoothctl In Docker Container [Solved]

Requirement	Configuration / Command
Network Mode	`--net=host`
Privileges	`--privileged`
Volume Mount	`-v /var/run/dbus:/var/run/dbus`
Base Image	Ubuntu or Debian (requires `bluez` package)

Table of Contents

What is running bluetoothctl in a Docker container?

Running bluetoothctl in a Docker container involves exposing the host machine’s Bluetooth hardware and the BlueZ protocol stack to a virtualized environment. By default, Docker containers are isolated from the host’s hardware, which leads to the common “Docker Bluetooth Pairing Failed” error.

To bridge this gap, the container must communicate with the DBus system bus. DBus is the messaging system used by Linux to manage hardware communications. By mounting the DBus socket and giving the container elevated privileges, you can manage Bluetooth devices directly from within a Dockerized application.

Step-by-Step Solutions

1. Prepare the Host System

Ensure the host machine has the Bluetooth service running and the necessary drivers installed. The container relies on the host’s BlueZ daemon (bluetoothd) to perform actual radio operations.

sudo systemctl start bluetooth
sudo systemctl enable bluetooth

2. Install bluez inside the Dockerfile

Your Docker image must contain the bluetoothctl utility. Add the bluez package to your Dockerfile to ensure the binary is available.

FROM ubuntu:latest
RUN apt-get update && apt-get install -y bluez
CMD ["/bin/bash"]

3. Execute the Docker Run Command

To successfully run bluetoothctl, you must use specific flags that grant the container access to the host’s hardware and communication bus. This is the most critical step to avoid pairing failures.

docker run -it \
  --net=host \
  --privileged \
  -v /var/run/dbus:/var/run/dbus \
  your-bluetooth-image

4. Running bluetoothctl inside the Container

Once inside the container’s shell, you can launch the Bluetooth control interface. Because you mounted the DBus socket, the tool will automatically detect the host’s Bluetooth controller.

bluetoothctl
# Inside the prompt:
power on
agent on
scan on
pair [DEVICE_MAC]
connect [DEVICE_MAC]

5. Troubleshooting “Pairing Failed”

If you still encounter “Pairing Failed” or “No default controller available,” check the following requirements:

Ensure the host’s bluetoothd is not being used exclusively by another process.
Verify that --privileged is enabled; standard containers cannot access the hardware kernel modules.
Confirm that the path /var/run/dbus exists on your host (some distributions might use different paths).