Skip to content
creadriPublic

About

KDE Proton Drive

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

kpdrive

Simple KDE Proton Drive sync Client designed to have a simple solution.

Screenshots

Main Window

Settings

Features

  • Sync ProtonDrive main folder
  • Photos Sync with some caviats
  • KDE and Dolphin integration
  • .protonignore with same syntax as .gitignore to ignore files to upload. .protonignore is still pushed though. .protonignore and .gitignore files in subfolders are honoured too, each for its own folder.
  • Localization support
  • Conditional Sync Pause currently based either on power management or network
  • Updates: the daemon looks for a new release once a day and installs it from the Fedora or Debian packages on click
  • Multiple accounts, each with its own folder, photos and ingestion settings, run by one daemon under one tray icon

Design decisions

  • Should be simple to use
  • Sync only, no FUSE mount
  • Using official proton-crypto-rs
  • kpdrive rus as daemon or as a CLI so it can be used separetely if wanted.

Photos handling

Messing with the timeline is harder than you might think.

  • Read-only timeline
  • Ingestion Folder: photos put in it go up to Proton Photos, then leave it

The timeline is copied down: kpdrive photos fetches once, and photos_sync has the daemon do it every half hour. Photos land in <photos_sync_folder>/YYYY/MM/, each file's modified time set to when the photo was taken. That folder may not be inside the sync folder, or the file sync would upload the whole library back into Drive as ordinary files. The first run downloads the whole timeline, which on most accounts is the largest thing kpdrive will ever do.

The copy is only a copy: a photo deleted in Proton is moved to the desktop trash on the next pass, a photo edited in Proton keeps its old copy, and deleting a local copy brings it back on the next pass. If the timeline ever lists none of the photos already downloaded, nothing is trashed: that looks more like a fault than a whole library deleted at once.

Ingestion is the other direction. Set photos_ingestion_folder (or pick it in the window) and the daemon uploads each photo or video put there into Proton Photos, then moves the file to the desktop trash, or deletes it with photos_ingestion_perm_rm. kpdrive ingest does one pass by hand when no daemon is running. Details:

  • A file goes up once it has stopped changing between two looks, so a copy in progress is left alone. The daemon looks every thirty seconds.
  • Taken: JPEG, PNG, WebP, GIF, TIFF, HEIC/HEIF, MP4 and MOV. Anything else stays.
  • The capture time comes from EXIF, with its recorded offset when there is one and in your local time zone otherwise, else from the file's modified time.
  • A photo Proton Photos already holds (same name and content, say because your phone backed it up) is not uploaded again, only removed locally.
  • HEIC and video go up without a timeline thumbnail, as kpdrive cannot decode them.
  • A file that fails stays in the folder and is tried again an hour later.

Photos Timeline Edge Cases

These are edge cases explaining why edit or pushing directly into the timeline isn't done yet

  • It's Proton Photos that will determine where in your timeline the photo is. As such, it's hard to make accurate predictions as it might evolve over time.
  • Editing a photo in a timeline might change the metadata and thus it might change the way Proton Photos puts your photo in the timeline.

Usage

kpdrive CLI / daemon

kpdrive login                 # browser sign-in, session stored in KWallet; adds an account
kpdrive accounts              # who is signed in, and where each account syncs
kpdrive status
kpdrive ls [path]
kpdrive get <remote> [local]
kpdrive put <local> [remote-folder]   # new file, or new revision if the name exists
kpdrive mkdir <remote>
kpdrive photos [--dest DIR]   # download the Photos timeline
kpdrive ingest [--folder DIR] # upload the ingestion folder into Photos once
kpdrive pause | resume        # stop syncing until resumed; survives restarts
kpdrive share <path> [--copy] [--password P] [--expires-days N]
kpdrive unshare <path>
kpdrive setup [--root DIR]    # local folder, ignore file, Places entry, autostart, launcher
kpdrive sync [--root DIR] [--watch] [--force]   # two-way Drive <-> local; --watch = daemon with tray
kpdrive logs [--search TERM] [--lines N] [--retention DAYS]
kpdrive logout [--remove]     # sign out; --remove also forgets the account (its files stay)
kpdrive update [--check]      # install the latest release's packages, then restart the daemon

With more than one account, pick one with --account NAME (-a, the start of a username is enough). Commands given a path inside a sync folder (share, unshare, rm, Dolphin's menu) work out the account from it; status, accounts, pause, resume and logs cover every account, and sync without --account syncs them all. A new account syncs to ~/ProtonDrive if nobody uses it and it is empty, otherwise to ~/ProtonDrive-<username>; kpdrive setup --account NAME --root DIR moves it.

Configuration

Stored in ~/.config/kpdrive/config.json. The window writes it, and the daemon re-reads it every pass, so a change takes effect without a restart (the sync folder is the exception: a running daemon keeps the one it started with). Missing keys take the default, so the file only needs what you change.

  • log_level : least severe line kept in the log, INFO, WARN or ERROR. WARN by default; the CLI prints its activity whatever this says

  • log_retention_days : Days of logs, 30 by default

  • sync_paused : boolean, true while paused by hand (kpdrive pause, the tray or the window): no file sync, photo download or ingestion. false by default

  • pause_on_networks : NetworkManager connection names, as the network applet shows them, that pause syncing while connected, such as a phone's hotspot. Checked at least every thirty seconds; a sync already under way finishes first. Empty by default

  • check_updates : boolean, true if the daemon asks GitHub once a day for a newer release. true by default

  • pause_on_power : power sources that pause syncing while in use, any of "ac", "battery" and "low_battery", as Plasma's power management tells them apart (low means the level set in System Settings; without PowerDevil, the kernel's battery level against 20%). "battery" covers a low battery too. ["low_battery"] by default

  • accounts : one entry per account, in the order they were added; the window and kpdrive login add them. Each has:

    • username : the Proton username
    • sync_folder : path of the folder to sync Proton Drive with. ~/ProtonDrive for the first account
    • photos_sync : boolean, true if the daemon downloads photos as well, every half hour. false by default
    • photos_sync_folder : path of the folder photos are copied into, by default ~/Pictures/ProtonDrive. May not be inside sync_folder
    • photos_ingestion_folder : path of a folder whose photos are uploaded into Proton Photos and then removed from it. Unset (off) by default. May not overlap sync_folder or photos_sync_folder
    • photos_ingestion_perm_rm : boolean, true if an ingested photo is deleted outright on successful upload, otherwise moved to trash. false by default

No two accounts may share or nest any of these folders. A configuration from before accounts (these keys at the top level) is moved into the first account the first time a newer kpdrive runs.

<sync_folder>/.protonignore lists paths sync leaves alone, in .gitignore syntax; the window's Ignore file… opens it. A .protonignore or .gitignore in any subfolder also applies, to that folder and below as in git, once it is on disk locally. Among files of one kind the nearest match wins, and a .protonignore wins over any .gitignore, so !.env in one keeps syncing a file a project's .gitignore leaves out. Ignore files inside an ignored folder are not read.

Logs

~/.local/share/kpdrive/logs/YYYY-MM-DD.log as plain text

Sync State

Sync state lives in ~/.local/share/kpdrive/accounts/<username>/state.json, one directory per account. Rules:

  • Edited on one side only: copied to the other side.
  • Edited on both sides: both versions are kept. The remote version takes the name; the local one becomes name (conflict copy 2026-09-19 18-30-26).ext and is uploaded as a new file in the same pass. Contents are compared first, so two identical files are never split into a copy. Timestamps in those names are UTC.
  • Deleted locally, unchanged remotely: trashed remotely (restorable in the web app).
  • Deleted locally but changed remotely: the remote version is restored, because a deletion must not discard someone else's edit.
  • Removed remotely: deleted locally only if untouched since we wrote it. Set KPDRIVE_DEBUG=1 for event-page diagnostics.

Photos Sync State

Photos are a separate volume with a flat, capture-time-ordered timeline, so photos is its own command and writes to <photos_sync_folder>/YYYY/MM/, ~/Pictures/ProtonDrive by default (what has been downloaded is recorded in the account's photos.json). It only downloads. The destination must be outside the file sync folder, or the file sync would upload the whole library back into Drive; kpdrive refuses that rather than letting it happen.

share returns a public read-only link. The URL ends in #<password>: that fragment never leaves the browser, so the link itself is the credential. Keep it secret, or add --password for a second one the recipient must type, which is deliberately not in the URL and has to be sent separately. Passing share a path that already has a link returns that link unchanged. --copy puts it on the clipboard and is what the Dolphin right-click entry uses; share accepts a local path inside the sync folder as well as a remote one.

The daemon (sync --watch) shows a Plasma tray icon, sends desktop notifications for conflicts and errors, and serves $XDG_RUNTIME_DIR/kpdrive.sock (line protocol: STATUS <path> → OK|SYNC|NONE, ROOT, STATE → one line of JSON for the window, SYNC, QUIT). The Dolphin overlay plugin in dolphin-overlay/ uses that socket; see its README.

Build

cargo build                 # CLI and daemon
cargo build -p kpdrive-ui   # the window; needs qt6-qtdeclarative-devel and kf6-kirigami

Translations

Catalogs live in po/ and are compiled into the binaries at build time, so there is nothing to install and gettext is a build dependency. The language comes from LC_ALL, LC_MESSAGES or LANG; anything without a catalog falls back to English.

./po/make-pot.sh                        # rebuild the template from Rust and QML,
                                        # and merge it into every existing .po
msginit --no-translator -l nl -i po/kpdrive.pot -o po/nl.po   # start a language
LC_ALL=fr_BE.UTF-8 kpdrive-ui           # see it

The window, the notifications and the wording the terminal shares with the window are translated. Log lines are not: they are a support tool, and a report nobody can grep is worth less than one in the wrong language. The rest of the terminal output is not translated yet.

Install

RPM

  1. Download rpm files from release that matches your distribution, ex: fc43 or fc44 for Fedora 43 & 44
  2. sudo rpm -i kpdrive<xxx>.rpm installs base daemon/cli
  3. sudo rpm -i kpdrive-dolphin<xxx>.rpm installs dolphin integration (icon overlay and right click menu)
  4. sudo rpm -i kpdrive-ui<xxx>.rpm installs KDE ui

DEB

Built on Debian 13 (trixie). apt is used rather than dpkg so the dependencies come with it; the ./ in front of the file name is what tells apt it is a file and not a package name.

  1. Download the deb files from the release, ignoring the -dbgsym ones (debug symbols, not needed to run)
  2. sudo apt install ./kpdrive_<xxx>_amd64.deb installs base daemon/cli
  3. sudo apt install ./kpdrive-dolphin_<xxx>_amd64.deb installs dolphin integration (icon overlay and right click menu)
  4. sudo apt install ./kpdrive-ui_<xxx>_amd64.deb installs KDE ui

Initial Setup

  1. kpdrive-ui to set-up your account in GUI (or see usage for CLI)
  2. kpdrive sync --watch to have daemon with tray

Don't forget to reload Dolphin to see icon overlay. Check Autostart to add kpdrive.

Updates

Once a day the daemon asks GitHub for the latest release. A newer one gets one notification, an entry in the tray menu and a line on the window's About page. On Fedora and Debian, when kpdrive came from the release packages, Update to x.y.z… downloads the packages you have installed (kpdrive, and kpdrive-ui and kpdrive-dolphin if present), checks each against the release's SHA256SUMS, and installs them with pkexec dnf or pkexec apt-get behind a password prompt. The daemon then restarts into the new version. An open window keeps the old one until reopened, and Dolphin loads the new overlay plugin the next time it starts.

Anywhere else (a source build, another distribution or Fedora release) the entry opens the release page instead. kpdrive update does the same from a terminal, and check_updates: false turns the check off.

Uninstall

RPM

sudo dnf remove kpdrive kpdrive-dolphin kpdrive-ui

DEB

sudo apt remove kpdrive kpdrive-dolphin kpdrive-ui

Releases

Pushing a version tag builds packages and publishes them as a GitHub release. The tag is the single source of truth for the version, and the workflow refuses to build if the crates disagree with it:

# bump both crates first, then
git commit -am "Release 0.x.0"
git tag -a v0.x.0 -m "kpdrive 0.x.0"
git push origin dev v0.x.0

A tag containing a hyphen (v0.x.0-rc1) is published as a pre-release, and .github/workflows/release.yml can also be run by hand against an existing tag.

Target Built in Packages
Fedora, current and previous release fedora:44, fedora:43 kpdrive, kpdrive-ui, kpdrive-dolphin (plus the source RPM)
Debian stable debian:trixie the same three as .deb

The release also carries SHA256SUMS, which the updater refuses to install without.

Bump the Fedora numbers in both workflows when Fedora moves on; every filename carries its dist tag, so which is which is never in doubt. The Debian build installs Rust through rustup rather than using the distro package, because Debian stable ships 1.85 while some dependencies want 1.92.

kpdrive holds the CLI and the daemon, kpdrive-ui the window, and kpdrive-dolphin the overlay icons and the context-menu entry. Installing them does not start syncing on its own; kpdrive setup is still how you choose a folder and opt into autostart.

Every push and pull request runs the build, the tests, the Dolphin plugin and a spec parse check on both Fedora releases, plus a fast validation of the Debian control and changelog files.

To build packages locally:

rpmbuild -ba --define "kpdrive_version 0.2.0" packaging/kpdrive.spec  # needs a matching tarball in ~/rpmbuild/SOURCES
dpkg-buildpackage -b -us -uc                                          # on Debian

Licence

GNU GPL v3 or later (GPL-3.0-or-later); see LICENSE.

Every library kpdrive links permits this. Qt 6 here is LGPL-3.0-only, which explicitly allows conveying the result under GPL v3. The KDE Frameworks behind the Dolphin plugin are LGPL-2.0-or-later, and KOverlayIconPlugin itself is LGPL-2.0-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL, so the v3 option applies. Three Rust dependencies are Apache-2.0 with no alternative (sync_wrapper at run time, clang-sys and codespan-reporting at build time); Apache-2.0 is compatible with GPL v3 and not with GPL v2, which is what ruled v2 out. Everything else is MIT, BSD, Unicode or dual MIT/Apache.

About

KDE Proton Drive

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages