KDEConnect - KDE UserBase Wiki

KDEConnect - KDE UserBase Wiki
Jump to content
From KDE UserBase Wiki
Other languages:
català
dansk
русский
українська
עברית
中文（简体）
Overview
This is the documentation page for
KDE Connect
. If you are developing, debugging, or building a release of
KDE Connect
, please refer to the
community page
KDE Connect
has two parts: the desktop program and the phone app.
What is KDE Connect?
KDE Connect
is a project that enables all your devices to communicate with each other. Here's a few things
KDE Connect
can do:
Receive your phone notifications on your desktop computer and reply to messages
Control music playing on your desktop from your phone
Use your phone as a remote control for your desktop
Run predefined commands on your PC from connected devices. See the list of example commands for more details.
Check your phone's battery level from the desktop
Ring your phone to help find it
Share files and links between devices
Browse your phone from your desktop
Control the desktop's volume using your phone
Send SMS from your desktop
Here's a nice overview video about the features from the YouTube channel Madhu.
Installation
You will most likely find the
KDE Connect
desktop component as a package in your distribution's repos. If not, you can ask them to package it.
Despite common misconception, you can use
KDE Connect
on all desktop environments. Since most of the developers are using Plasma, it may occur that a feature is broken or inaccessible on other desktop environments. In this case, please file a
bug report
There are multiple ways to enhance the
KDE Connect
experience on non-Plasma desktops. If you are a GNOME user you might prefer
GSConnect
, a GNOME shell extension. For desktops with AppIndicator support (Budgie, Cinnamon, LXDE, Pantheon, Unity), KDE Connect already comes with the
kdeconnect-indicator
binary, which can be set to autostart in each environment.
The app for Android can be found in both the
Google Play Store
and the free and open store
F-Droid
The app for iOS can be found in
Apple's proprietary App Store
. Additionally, a pre-release, testing version of KDE Connect can be downloaded from
TestFlight
. Please see the
iOS README
for important data disclosure information, known limitations, and bug reporting information.
KDE Connect
is also available for SailfishOS via
sailfish-connect
and we are working on bringing it to other Linux-based phones (Plasma Mobile, PostmarketOS etc.)
See KDE Connect download page
for installation links for other platforms (including Windows and macOS).
Pairing two devices together
First, you need to open
KDE Connect
on your computer
and
phone. You should now be able to see in each screen the name of the device you wish to pair with. If it's not working, make sure that the two devices are connected to the same network and that there isn't any firewall blocking the two devices from seeing each other. See the
troubleshooting section
You can now request pairing in one of the two devices. The other device will show a prompt asking to accept the pairing request. Confirm it and that's it! Your devices are now paired.
While a typical configuration might include one computer and one phone, it's also possible to pair two computers instead.
Pairing devices without automatic discovery
Android
On the
KDE Connect Devices
screen open the 3 dot menu in the top right. Choose
Add devices by IP
KDE
Add the
customDevices
line in
~/.config/kdeconnect/config
[General]
name=fedora
customDevices=192.0.2.42,192.0.2.43
Bluetooth Connectivity
In recent versions (for example v24.08.1) bluetooth connectivity has been enabled by default. To use this, you must first bluetooth pair your computer and phone.
Click Add device:
Make sure your phone is visible to pairing and it will appear, once appeared click pair:
It will pop up with a PIN to be confirmed on both the computer and the phone:
Click matches on the desktop and pair on Android
It will then be connected correctly:
Once this has been achieved open the KDE Connect on Android and enable bluetooth
On the "Add new devices" page, the computer should appear and the pairing process can be followed as usual. Refreshing this view can force the phone to attempt to rediscover.
This may take some time to appear, both Android and Bluez seem to implement quite a lot of caching and this can delay how long it takes to be detected
Browser Integration
Plasma Browser Integration
makes
KDE Connect
even more powerful. It allows you to control content from e.g. Youtube or Netflix from your phone and send browser tabs to your phone. Despite the name, it can also be used on non-Plasma desktops.
Changing Device Names
You can only change the name of your device on the device itself. So if you want to change the name of your computer then you must use the desktop program and if you want to change the name of your phone or tablet you must make the change in the
KDE Connect
app. Once a device is renamed, it will automatically sync with all other connected devices.
Running KDE Connect over OpenVPN
There may be a variety of reasons for using
KDE Connect
with a VPN. Maybe you have left home and want to run a command, or maybe you’re on a public wifi network where your devices aren’t allowed to communicate and you want to use the remote control to give a presentation.
Set up OpenVPN
If you have your own server with a public-facing IP address, you can set up
OpenVPN
yourself. It is not the easiest piece of software to set up, but by following a setup tutorial such as
this one
, you should be able to manage.
In order to allow UDP broadcast packets, which are what
KDE Connect
uses to automatically discover two devices,
OpenVPN
needs to be set up for bridging (TAP device). If you use a tun device, you can still manually connect by IP address.
If you want to rent a pre-configured
OpenVPN
service rather than set up your own, it should work, but the same considerations about the server settings need to be taken into account.
Once the server is running, you can use the official
OpenVPN
client to connect the desktop to the server. There is no official
OpenVPN
client for Android, but the
OpenVPN for Android
client works well:
openvpn
Once both devices are connected, test that they are able to communicate over the VPN by trying to do a network ping between them.
Configure KDE Connect
If your
OpenVPN
instance is set up for bridging,
KDE Connect
should work just like on a local network.
If you are using
OpenVPN
with a tun device, you will have to manually add your devices by IP. Then, once you connect to the VPN,
KDE Connect
should automatically detect your device and either connect or be ready for pairing!
Available Plugins
Battery Monitor
"Show your phone battery next to your computer battery."
By enabling this, the
KDE Connect
widget on your panel tray will display your phone's battery.
Clipboard
"Share the clipboard between devices."
With this, you can simply copy text from your computer and it will be immediately available to paste on your phone, and vice-versa. This does not work with images though.
Auto-sync on Android 10+
Android 10 prevents apps from accessing the clipboard to prevent malicious apps from accessing your data. This makes the clipboard plugin in KDE Connect uncomfortable to use.
On Android 10+, there's an action button labeled "Send Clipboard" in the persistent indicator notification.
On Android 14+, there's a tile in the pull-down menu called "Send clipboard", that can be moved to a convenient slot (e.g. in the partial pull-down section).
Magisk Module (root only)
If you are rooted, you can use a Magisk module to remove this restriction.
Log Reading
If you have a build containing commit
edc655da5ac1eb5c3027c8556cc62037a1d4c5ac
, you can enable the READ_LOGS permission in order to enable a workaround to clipboard sync.
Enable
USB debugging
on your phone.
Run these commands:
adb
-d
shell
pm
grant
org.kde.kdeconnect_tp
android.permission.READ_LOGS
adb
-d
shell
appops
set
org.kde.kdeconnect_tp
SYSTEM_ALERT_WINDOW
allow
adb
-d
shell
am
force-stop
org.kde.kdeconnect_tp
How does it work?
With log reading enabled, KDE Connect watches its own log. If it sees a line indicating that it has been denied access to read the clipboard, it pops up an invisible window to the foreground, grabs the clipboard, and closes the window.
Contacts
"Synchronize contacts between devices"
This plugin silently synchronizes contacts, in vcard format, from your phone to your desktop.
As of this writing, the synchronization is one-way, with data being sent from the Android implementation to the desktop, to be consumed by any application which uses the KPeople library with the KPeopleVCard plugin, such as the KDE Connect SMS app.
VCard Location
On non-Windows platforms, contact cards are written to
QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation) + "/kpeoplevcard"
. This might be configured differently by your system, but normally resolves to
~/.local/share/kpeoplevcard
On Windows, the path resolves to
%LocalAppData%
Inhibit Screensaver
"Inhibit the screensaver when the device is connected."
This makes sure that your screensaver will not run while your device is connected.
Multimedia Control Receiver
"Remote control your music and videos."
With this feature, you can control your music and videos remotely, with pause/play, previous/next, 5 s before/later. You can also change which media player to control, in addition to application and system volume.
Multimedia control receiver with KDE Connect in Android
Pause Media During Calls
"Pause music/videos during a phone call."
Pause music/videos during a call. This feature can be powerful when combined with
Plasma Browser Integration
. For example, when you are listening to some music on Peertube or Youtube, the video will be paused whenever you receive a call.
You can configure this option to pause only when you pick up your phone or directly when your phone starts to ring. You can also decide if you want to only pause the media player or/and mute the system sound.
Ping
"Send and receive pings."
This serves to test your connection to a given device. Once selected, a "Ping!" will appear as a notification on your receiving device.
On your desktop, you can send a ping through the KDE Connect settings or through the widget on the tray.
On your phone, you can send a ping through the upper right hamburger menu on the
KDE Connect
app.
Send a ping to your computer with android
Receive Notifications
"Show your phone notifications on your computer and keep them in sync."
This keeps you in touch with what happens on your phone! Any notifications you receive on your phone will be shown in your computer. Some notifications, such as those of Instant Messengers (IM) like Telegram can be replied on the fly through the computer notification itself.
Remote File System Browser
"Browse the remote device filesystem using SFTP."
This allows you to access your phone storage! When enabled, a device will appear in Dolphin with which you can navigate your external storage.
Ring My Phone
"Find your lost phone by making it play an alarm sound."
This also serves to test your connection to a given device, and by ringing your phone remotely, you can quickly find its location!
Run Commands
"Execute console commands directly."
With
KDE Connect
, you can run predefined commands on your computer by pressing buttons on your phone!
Instructions on how to add a command are shown in
userbase
. A set of useful commands can also be found
here
Some sample commands, such as suspend and lock screen, are also available.
If your device supports Device Controls (Android 11+), KDE Connect will display configured commands there. You can then quickly control your remote device, such as locking the screen. See Google's documentation for more description of device controls:
Screenshot of the device controls pane on a Samsung device
Send Notifications
"Broadcast this computer's notifications, so they can be shown on other devices."
This is pretty self-explanatory: notifications from your computer will show up on your phone.
You can configure if you want to send the notification description, the icons pertaining to the application and persistent or very important notifications.
This keeps you in touch with what happens on your computer! Any notifications you receive on your computer will be shown in your phone.
Sensitive Notification Content (Android 15+)
On Android 15+, "sensitive" notification content is hidden by the system when passed to applications. Due to this limitation, KDE Connect will show something like "Sensitive notification content hidden" instead of the real content.
(Recommended) Grant RECEIVE_SENSITIVE_NOTIFICATIONS
KDE Connect can be granted the RECEIVE_SENSITIVE_NOTIFICATIONS permission, at which point sensitive notification content will be delivered normally. This may not work on all manufacturer's devices.
Set up ADB (
).
Connect the phone over ADB, either with USB or wireless ADB.
Run
adb
shell
cmd
appops
set
--user
org.kde.kdeconnect_tp
RECEIVE_SENSITIVE_NOTIFICATIONS
allow
If you're facing a permission related exception:
java.lang.SecurityException: uid 2000 does not have android.permission.MANAGE_APP_OPS_MODES.
upon running above command, enable
Disable permission monitoring
in
Developer Options
, reboot the phone and then run above command.
Reboot the phone.
Disable Enhanced Notifications
In the notification settings for the app you want to send unrestricted notifications, disable "Enhanced notifications" which will remove this restriction.
Note that this will disable
all
enhanced notification functionality, such as being able to reply to messages from notifications, etc.
Share and Receive
"Receive and send files, URLs or plain text easily."
This integrates your desktop and your browser so that you can right-click on files or links and send it immediately to your phone!
Files show the right-click option "Send to phone via KDEConnect" and will send the file directly, showing it among your notifications.
Links show the right-click option "Open on phone" and will automatically open your phone's default browser on the chosen website. Really handy!
When receiving files from your phone into your computer, they will go to your Downloads folder by default. If you wish, you can change that too.
Telephone Integration
"Show notifications for incoming calls."
Whenever you get a call on your phone, a notification telling you which number is calling appears. Paired with "Pause media during calls", you'll surely be able to answer readily and never lose a call!
Virtual Input
"Use your phone as a touchpad and keyboard."
With this enabled, by going to your phone app and selecting Remote input, a touch screen will immediately be available for you to control your computer mouse, similarly to a touchpad. One touch equals one click.
The keyboard icon in the upper right allows you to type on your phone and see the result on your computer too.
If you press the hamburger menu right by its side, you'll be able to send right and middle clicks.
Presentation control
It is possible to control presentations using the previous/next slide button. When the device is locked, you can use the volume up/down button to do that. You can also highlight something using the laserpointer. Just move your phone and the blue circle will follow! Using the hamburger menu, you can toggle fullscreen (F5) or quit the presentation (Esc).
Permissions Explanations and Tutorial Videos
From time to time, Google will require video submissions to prove that we use permissions in ways which are allowed by Play Store policies. Those videos are gathered here for future reference, but also because they provide nice tutorials of how to use certain features, and are also useful to demonstrate permissions usage to a wider audience.
Android Mouse Receiver (Accessibility Permission)
In order to be a fake input device, Android requires that we take the Accessibility permission. The mouse receiver plugin is demonstrated in the following video.
Other Permissions
This video demonstrates several KDE Connect features, in particular it demonstrates how KDE Connect uses certain privacy-impacting permissions, such as the SMS permissions.
Missing or limited features on some platforms
Some platforms are missing some features due to technical limitations or other reasons.
iOS
Missing
Notification sync
SMS
Keeping connection alive when app is not on-screen
Virtual Display
One way - only from iOS to desktop
Remote Input
Run Command
Slideshow Remote
Shared clipboard (limited, need to tap "push clipboard" on the app to push clipboard to the PC)
Android
Missing
Virtual Display
One way - only from Android to desktop
Run Command
Slideshow Remote
SMS (transfer messages to desktop and handle sending)
Contacts
One way - only from desktop to Android
SMS (retrieve from phone and dispatch send requests to phone)
Troubleshooting
I have two devices running KDE Connect on the same network, but they can't see each other
KDE Connect
uses dynamic ports in the range 1714-1764 for UDP and TCP. So if you are behind a firewall, make sure to open this port range for both TCP and UDP. Otherwise, make sure your network is not blocking UDP broadcast packets.
Check that the process is listening on the network:
sudo
netstat
-tunelp
grep
-i
kdeconnect
Are the ports open/blocked?
netcat
-z
-v

1714
-1764
Example output:
Connection to 1716 port [tcp/*] succeeded!
You also get lots of Connection refused, but you need 1 “succeeded”
If the network connection is not the problem, you might try starting from a clean configuration again:
killall
kdeconnectd
mv
~/.config/kdeconnect
~/.config/kdeconnect.bak
ufw
If your firewall is
ufw
, you can open the necessary ports with:
sudo
ufw
allow
1714
:1764/udp
sudo
ufw
allow
1714
:1764/tcp
sudo
ufw
reload
Note
A user has suggested this for better security:
sudo
ufw
allow
proto
tcp
from
192
.168.1.0/24
to
any
port
1714
:1764
sudo
ufw
allow
proto
udp
from
192
.168.1.0/24
to
any
port
1714
:1764
firewalld
If your firewall is
firewalld
, you can open the necessary ports with:
sudo
firewall-cmd
--permanent
--zone
--add-service
kdeconnect
sudo
firewall-cmd
--reload
Note
This allows KDE Connect to be accessed from outside while you're in the "home" zone. A zone can be assigned to your WiFi connection in network settings. For safety, you should rather avoid running KDE Connect in "public" zone.
Firewall Configuration (firewall-config)
Open Firewall Configuration (
firewall-config
). In
Zones
Services
, check the kde-connect service.
Make sure you choose the "Permanent"
Configuration:
option in the drop-down menu at the top, otherwise rebooting will discard your settings changes.
iptables
If your firewall is
iptables
, you can open the necessary ports with:
sudo
iptables
-I
INPUT
-i

-p
udp
--dport
1714
:1764
-m
state
--state
NEW,ESTABLISHED
-j
ACCEPT
sudo
iptables
-I
INPUT
-i

-p
tcp
--dport
1714
:1764
-m
state
--state
NEW,ESTABLISHED
-j
ACCEPT

sudo
iptables
-A
OUTPUT
-o

-p
udp
--sport
1714
:1764
-m
state
--state
NEW,ESTABLISHED
-j
ACCEPT
sudo
iptables
-A
OUTPUT
-o

-p
tcp
--sport
1714
:1764
-m
state
--state
NEW,ESTABLISHED
-j
ACCEPT
nftables
If you are using
nftables
, you could open the required ports with something like:
table
inet
filter
set
lan_v4
type
ipv4_addr
flags
interval
elements
10
.0.0.0/8,
172
.16.0.0/12,
192
.168.0.0/16,
169
.254.0.0/16
chain
input
ct
state
established,related
accept
comment
"Accept traffic originating from us"
ip
saddr
@lan_v4
meta
l4proto
udp,
tcp
th
dport
1714
-1764
ct
state
new
accept
comment
"Accept new KDE Connect on ip local net"
There will be more to your `nftables.conf`, but here is how one could load it safely, given a project source directory containing `etc/nftables.conf` and a `makefile` at the root of the project source directory:
.DEFAULT_GOAL
:=
check
nftables
nftables.conf
check
sudo
nft
--check
--file
etc/
$(
nftables
install
check
sudo
cp
etc/
$(
nftables
/etc
sudo
systemctl
reload
nftables.service
sudo
systemctl
restart
fail2ban.service
You will have to set everything up and of course say `make` to check and `make install` to load and activate.
KDE Connect crashes or restarts when trying to pair with another device
Sometimes, a corrupt config file may cause
KDE Connect
to crash when trying to pair with a device. In that case, deleting the config ~/.config/kdeconnect might help.
KDE Connect Android app crashes
If the KDE Connect Android app crashes, you might be able to get more information about the crash by using
adb logcat
Set up ADB using the
official instructions
The following command should list all information relevant to your crash. Run
adb logcat
*before* triggering the crash.
adb
logcat
--pid
$(
adb
shell
pidof
-s
org.kde.kdeconnect_tp
Can I run KDE Connect without a display server?
Yes, you can pass the command line argument
-platform offscreen
to the daemon (eg:
killall -9 kdeconnectd; /usr/lib/libexec/kdeconnectd -platform offscreen
GSConnect
GSConnect
is an independent project which implements the
KDE Connect
protocol into GNOME and uses the same Android app. If you are running
GSConnect
, please visit that project's
GitHub page
first for support. If you and the
GSConnect
team determine the issue is the Android app or protocol, feel free to report those in the
KDE Connect
bug tracker.
Bluetooth
Check the logs for KDE Connect; a normal set of logs looks like:
The logs can usually be read with journalctl:
journalctl --user
[email protected]
and should contain several mentions of bluetooth. If there is a log like:
qt.bluetooth.bluez: Bluetooth device is powered off
then the daemon was started when bluetooth was disabled and will need to be restarted until a release including
is released.
If everything looks correct from the logging perspective then it is worth confirming that the bluetooth interface has had the service uuid added to it (this is what the client application will connect to). If you run
bluetoothctl show
there will be a list of UUIDs on the interface, and it should include
UUID: Vendor specific (185f3df4-3268-4e3f-9fca-d4d5059915bd)
If it does not, then there is a problem registering the UUID on the interface and you should restart kdeconnectd and check the logs etc for information.
Debug logging
On many systems (including Debian/Ubuntu and Arch) kdeconnect is autostarted as a systemd user unit, you can enable debug logging by doing the following as the user (not root, do not use sudo):
systemctl
edit
--user
[email protected]
Add the following content:
[Service]
Environment=QT_LOGGING_RULES="*.debug=true; qt.debug=false;"
then save and exit the file.
Restart the unit:
systemctl
restart
--user
[email protected]
Logs can then be seen with journalctl:
journalctl
--user
-u
[email protected]
My problem is not in this list :(
In case you find a bug and want to report it, you can do so in the
KDE bug tracker
Retrieved from "
Category
Pages with syntax highlighting errors