Install¶

BlueFerry ships as native packages for each distribution. Install blueferry-backend plus the client for your desktop. The backend package also contains the blueferry-tui terminal client.

Download the packages for your distribution from the latest release, then run the matching command in the folder that contains them.

Arch Linux and CachyOS¶

sudo pacman -U ./blueferry-backend-*.pkg.tar.zst ./blueferry-gtk-*.pkg.tar.zst

Debian, Ubuntu, Linux Mint, Pop!_OS, and PikaOS¶

sudo apt install ./blueferry-backend_*.deb ./blueferry-gtk_*.deb

Ubuntu 24.04, Linux Mint 22.3, and Pop!_OS 24.04 don't provide the Qt dependencies; use the GTK or terminal client there.

Fedora¶

Fedora 43 and 44 share the .fc43 packages; Fedora 45 uses .fc45.

# Fedora 43 and 44; use fc45 for Fedora 45.
sudo dnf install ./blueferry-backend-*.fc43.noarch.rpm \
  ./blueferry-gtk-*.fc43.noarch.rpm

Replace blueferry-gtk with blueferry-qt for KDE Plasma.

Gentoo, Alpine, and other systems without systemd¶

There are no packages for these yet. BlueFerry runs there from a source install; see Running without systemd.

WSL2 on Windows¶

The Debian packages work in a WSL2 distribution once a USB Bluetooth adapter is passed in from Windows and a few WSL2 differences are handled; see Running under WSL2.

Bluetooth changes made by the packages¶

• Arch and Fedora packages require BlueZ 5.86 or newer and add a bluetooth.service drop-in that runs bluetoothd -E -P hfp. That enables the BlueZ interface needed for iPhone system notifications and leaves out BlueZ's own hands-free plugin, which would get in the way of the optional phone calls. Bluetooth is restarted only if it is already running.
• Debian-family packages don't change or restart Bluetooth. Messages and contacts work; system notifications are added only when that machine's BlueZ already supports them.

Tested distributions¶

Details are in packaging/README.md.

Build packages from source¶

git clone https://github.com/erikwb/blueferry.git
cd blueferry

Arch-based distributions: build and install all packages. Without -i, the packages are only built, into packaging/arch/.

sudo pacman -S --needed base-devel python
./build.sh -si

The build always uses /usr/bin/python, ignoring any virtualenv, pyenv, conda, or mise interpreter earlier in PATH.

Debian-based distributions: packages are written to dist/deb/.

sudo apt-get install devscripts equivs
sudo mk-build-deps -i -r -t 'apt-get -y --no-install-recommends' packaging/deb/control
./packaging/build-deb.sh

Fedora: packages are written to dist/rpm/.

sudo dnf install dnf-plugins-core rpm-build
sudo dnf builddep packaging/rpm/blueferry.spec
./packaging/build-rpm.sh

Upgrades and removal¶

Package upgrades are detected automatically: an outdated backend restarts itself, and clients ask you to update if they no longer match the backend.

Uninstalling doesn't delete your configuration in ~/.config/blueferry or your local data in ~/.local/state/blueferry. Remove those folders yourself if you want a clean slate.

Next step¶

Pair your iPhone.