Use
bluetoothctl to manage Linux Bluetooth devices through an interactive command-line interface. This guide covers essential commands for scanning, pairing, connecting, and troubleshooting adapters to ensure reliable device integration.
Starting the Service and Entering the Shell
Before managing devices, ensure the Bluetooth service is active. On most modern distributions using systemd, you can check the status with
systemctl status bluetooth. If it is not running, start it with
sudo systemctl start bluetooth. To enable it at boot, run
sudo systemctl enable bluetooth. Once the service is confirmed active, launch the tool by typing
bluetoothctl in your terminal. You will see a prompt change to
[bluetooth]#, indicating that the interactive shell is ready for input. This environment allows you to execute complex sequences of commands without needing to restart the daemon repeatedly.
Scanning for Available Devices
The first step in connecting any peripheral is discovering what is available nearby. Use the
scan on command to begin listing nearby devices. The output will display MAC addresses alongside device names. For example, you might see entries like
Device A4:C3:F0:12:34:56 MyHeadset. Keep the scan running while you put your device into pairing mode. Most keyboards, mice, and headphones require a specific button combination or long press to become discoverable. Once you have identified the correct MAC address, stop the scan with
scan off to save battery life on the peripheral and reduce network noise. Note that some older devices may not appear immediately; waiting a few seconds or moving closer to the receiver often helps.
Pairing and Trusting Devices
Pairing establishes the cryptographic keys necessary for secure communication. Identify the target device by its MAC address from the previous scan. Enter
pair [MAC_ADDRESS] to initiate the handshake. Depending on the device, you may need to enter a PIN code or confirm a passkey displayed on both screens. After successful pairing, trust the device using
trust [MAC_ADDRESS]. This ensures the system remembers the security keys and skips the pairing process during future connections. Without trusting, you would be forced to re-pair every time the connection drops, which is inefficient for daily drivers like headphones or keyboards.
Connecting and Managing Links
With the device paired and trusted, you can establish an active connection using
connect [MAC_ADDRESS]. The prompt will update to show the current state, such as
[CHG] Device ... Connected: yes. If the connection fails, check if another application has grabbed the adapter exclusively. Some audio servers or virtualization software may lock the Bluetooth controller. You can list currently connected devices with
list or view detailed information about a specific device using
info [MAC_ADDRESS]. To disconnect, simply use
disconnect [MAC_ADDRESS]. This leaves the device paired and trusted for next time.
Troubleshooting Common Issues
If devices fail to connect, verify the agent settings. Use
agent KeyboardDisplay to allow PIN entry via the terminal, which is crucial for pairing peripherals that do not have their own displays. Sometimes, the adapter itself needs a reset. You can power cycle the adapter within the shell using
power off followed by
power on. This forces the kernel driver to reload and clears stale states. If you encounter persistent errors, check the system logs with
journalctl -u bluetooth -f while attempting to connect. This real-time log view reveals why the handshake failed, whether due to permission issues, hardware incompatibility, or signal interference. For users struggling with external hardware, see
Making a USB Bluetooth Adapter Work on Linux Instead of Internal Bluetooth if your internal chip is unreliable.
Automating Connections
While manual management is useful, automating connections saves time. You can write scripts that pipe commands into
bluetoothctl via standard input. However, for permanent setups, configuring the system to auto-connect is often better. Refer to our guide on
How to Connect Bluetooth Permanently in Linux for details on configuring udev rules and systemd services to handle reconnection automatically after reboot or sleep cycles.
Frequently Asked Questions
Why does my keyboard type random characters after connecting?
This usually indicates a mismatch in the encryption key or a firmware glitch in the keyboard. Remove the device from the trusted list using
remove [MAC_ADDRESS], then pair it again. Ensure you are using the latest firmware for your peripheral, as many manufacturers release fixes for Linux compatibility issues.
Can I use bluetoothctl with headless servers?
Yes, but you must configure the agent correctly. Use
agent NoInputNoOutput for devices that do not require user interaction. This prevents the shell from hanging while waiting for a PIN entry that cannot be provided on a server without a monitor.
What if bluetoothctl says "Connection Failed"?
Check if the device is already connected to another machine, such as a phone or tablet. Bluetooth devices often refuse new connections if they are actively linked elsewhere. Disconnect them from the other host first, or use
disconnect on the existing session before retrying.
How do I fix "Permission Denied" errors?
Ensure your user is part of the
bluetooth group. Run
sudo usermod -aG bluetooth $USER and then log out and back in. Additionally, verify that no other process is locking the D-Bus interface used by the tool.
Does this work with Windows dual-boot systems?
Bluetooth stacks are independent per operating system. Pairing in Linux does not carry over to Windows. You must pair the device separately within each OS. Using the same MAC address for both systems is common, but the security keys are stored locally in each installation.