mirror of
https://github.com/narrrl/proton-drive-linux.git
synced 2026-11-16 17:51:59 +01:00
The release .tar.gz held the four binaries and their translations only, and the service unit pointed at /usr/bin/pdfs, so it was no install on its own. It now carries a /usr-like tree (bin, share, the user unit, the tray's autostart entry) and install.sh, which installs it into ~/.local without root: - checks the libraries with ldd and names the packages to install per distribution, and that fusermount3 is there and setuid; - refuses to install next to a package of the client; - rewrites Exec= and ExecStart= to absolute paths, since ~/.local/bin is often not on a session's PATH; - keeps a manifest, removes what an older version left, restarts a running service on update, and --uninstall leaves settings alone. packaging/tarball/build.sh lays the tarball out and test.sh installs, updates and uninstalls it in a throwaway home; the release job runs both, CI runs shellcheck on them. The app looks for its translations in share/locale beside its own bin directory and starts the tray from there, so nothing needs PDFS_LOCALEDIR or the PATH. The -bin AUR package takes every file from the new tarball instead of raw.githubusercontent.com. INSTALL.md documents the tarball and layering the COPR package on Fedora Atomic.
426 lines
17 KiB
Markdown
426 lines
17 KiB
Markdown
# Installation
|
|
|
|
Install Proton Drive for Linux from your distribution's package, sign in, and keep it up to date.
|
|
This page also covers building from source, running without a desktop, and removing the client
|
|
again.
|
|
|
|
- [Install a package](#install-a-package)
|
|
- [Optional extras](#optional-extras)
|
|
- [First run](#first-run)
|
|
- [Updating](#updating)
|
|
- [Uninstalling](#uninstalling)
|
|
- [Headless and server use](#headless-and-server-use)
|
|
- [Build from source](#build-from-source)
|
|
- [What the packages install](#what-the-packages-install)
|
|
|
|
## Install a package
|
|
|
|
| Distribution | Package | Updates |
|
|
|---|---|---|
|
|
| [Fedora 44 or newer](#fedora-44-or-newer) | COPR repository `narl-rs/proton-drive-linux` | With `dnf upgrade` |
|
|
| [Arch Linux](#arch-linux-aur) | `proton-drive-for-linux` in the AUR | With your AUR helper |
|
|
| [Debian, Ubuntu 24.04 or newer](#debian-and-ubuntu-2404-or-newer) | `.deb` from the release page | Download each release |
|
|
| [NixOS](#nixos-flake) | The flake in this repository | With `nix flake update` |
|
|
| [Fedora Atomic](#fedora-atomic-silverblue-kinoite-bazzite-bluefin) (Silverblue, Kinoite, Bazzite, Bluefin) | The COPR repository, layered with `rpm-ostree` | With `rpm-ostree upgrade` |
|
|
| [Anything else](#other-distributions), immutable ones included | `.tar.gz` from the release page, installed into your home folder by its `install.sh`, or [build from source](#build-from-source) | Run the new release's `install.sh` |
|
|
|
|
Release packages are for x86_64. You also need a Secret Service provider, such as GNOME
|
|
Keyring, KWallet or KeePassXC, to keep your session. Most desktops have one already.
|
|
|
|
### Fedora (44 or newer)
|
|
|
|
Enable the [COPR repository](https://copr.fedorainfracloud.org/coprs/narl-rs/proton-drive-linux/)
|
|
and install the package:
|
|
|
|
```bash
|
|
sudo dnf copr enable narl-rs/proton-drive-linux
|
|
sudo dnf install proton-drive-linux
|
|
```
|
|
|
|
COPR builds every release for Fedora 44, 45 and Rawhide, so `sudo dnf upgrade` keeps the client
|
|
up to date along with the rest of your system.
|
|
|
|
You can also download the signed `.rpm` from the
|
|
[latest release](https://github.com/narrrl/proton-drive-linux/releases/latest). It installs the
|
|
same files, but you have to download each new version yourself:
|
|
|
|
```bash
|
|
sudo dnf install ./proton-drive-linux-*.x86_64.rpm
|
|
```
|
|
|
|
To build an RPM from your own checkout, see [Build an RPM locally](#build-an-rpm-locally).
|
|
|
|
### Arch Linux (AUR)
|
|
|
|
Three packages cover the usual choices. They conflict with each other, so install one:
|
|
|
|
| Package | Contents |
|
|
|---|---|
|
|
| [`proton-drive-for-linux`](https://aur.archlinux.org/packages/proton-drive-for-linux) | Latest release, built from source |
|
|
| [`proton-drive-for-linux-bin`](https://aur.archlinux.org/packages/proton-drive-for-linux-bin) | Latest release, prebuilt binaries |
|
|
| [`proton-drive-for-linux-git`](https://aur.archlinux.org/packages/proton-drive-for-linux-git) | The newest code on `main`, built from git |
|
|
|
|
```bash
|
|
paru -S proton-drive-for-linux # or yay, or any other AUR helper
|
|
```
|
|
|
|
The recipes are in [`packaging/aur/`](../packaging/aur/README.md).
|
|
|
|
### Debian and Ubuntu (24.04 or newer)
|
|
|
|
Download the `.deb` from the [latest release](https://github.com/narrrl/proton-drive-linux/releases/latest)
|
|
and install it:
|
|
|
|
```bash
|
|
sudo apt install ./proton-drive-linux_*_amd64.deb
|
|
```
|
|
|
|
There is no APT repository yet, so repeat this for each new release. Turn on **Check for
|
|
updates** in **Preferences** to be told when one is out.
|
|
|
|
### NixOS (flake)
|
|
|
|
The repository is a flake. Add it as an input and enable the module. The module installs the
|
|
package, starts the user service in every graphical session, and turns on the `fusermount3`
|
|
wrapper and GNOME Keyring for you:
|
|
|
|
```nix
|
|
{
|
|
inputs.proton-drive-linux.url = "github:narrrl/proton-drive-linux";
|
|
|
|
outputs = { nixpkgs, proton-drive-linux, ... }: {
|
|
nixosConfigurations.<host> = nixpkgs.lib.nixosSystem {
|
|
modules = [
|
|
proton-drive-linux.nixosModules.default
|
|
{ services.proton-drive-linux.enable = true; }
|
|
];
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
That URL follows `main`. To stay on releases, pin the input to a release tag instead, and change
|
|
the tag to update:
|
|
|
|
```nix
|
|
inputs.proton-drive-linux.url = "github:narrrl/proton-drive-linux/v3.8.0";
|
|
```
|
|
|
|
Each release tag is built with Nix before the release is published.
|
|
|
|
#### Binary cache
|
|
|
|
CI uploads every build of `main` and of each release tag to a Cachix binary cache, so Nix can
|
|
download the client instead of compiling it. A system build does not read a flake input's cache
|
|
settings, so add the cache to your NixOS configuration once:
|
|
|
|
```nix
|
|
nix.settings = {
|
|
substituters = [ "https://proton-drive-linux.cachix.org" ];
|
|
trusted-public-keys = [
|
|
"proton-drive-linux.cachix.org-1:w1+3pXVXyTlqkFGn3dWpUhlaJtyGhSm3X0mFwfa++AA="
|
|
];
|
|
};
|
|
```
|
|
|
|
The cache holds the build against the `nixpkgs` this flake locks. Setting
|
|
`inputs.proton-drive-linux.inputs.nixpkgs.follows = "nixpkgs"` builds against yours instead,
|
|
which the cache does not have, so Nix compiles it. `nix run` and `nix shell` ask whether to use
|
|
the cache the first time; answer yes, or run `cachix use proton-drive-linux`.
|
|
|
|
To try it without changing your system, run it straight from the flake:
|
|
|
|
```bash
|
|
nix run github:narrrl/proton-drive-linux#proton-drive-linux -- --help # the CLI
|
|
nix shell github:narrrl/proton-drive-linux -c pdfs-app # the desktop app
|
|
```
|
|
|
|
The mount needs the setuid `fusermount3` from NixOS (`programs.fuse.enable`, on by default with
|
|
the module) and a Secret Service such as GNOME Keyring or KWallet. To leave out ffmpeg, and with
|
|
it video thumbnails, override the package with `withFfmpeg = false`. The recipe is in
|
|
[`packaging/nix/`](../packaging/nix/).
|
|
|
|
### Fedora Atomic (Silverblue, Kinoite, Bazzite, Bluefin)
|
|
|
|
The system is read-only, so layer the COPR package on top of it. It brings its libraries along:
|
|
|
|
```bash
|
|
sudo curl -o /etc/yum.repos.d/proton-drive-linux.repo \
|
|
"https://copr.fedorainfracloud.org/coprs/narl-rs/proton-drive-linux/repo/fedora-$(rpm -E %fedora)/narl-rs-proton-drive-linux-fedora-$(rpm -E %fedora).repo"
|
|
rpm-ostree install proton-drive-linux
|
|
systemctl reboot
|
|
```
|
|
|
|
`rpm-ostree upgrade` brings new releases with the system's own updates.
|
|
|
|
### Other distributions
|
|
|
|
The `.tar.gz` from the [latest release](https://github.com/narrrl/proton-drive-linux/releases/latest)
|
|
installs into your home folder, without root, so it also works where the system is read-only:
|
|
|
|
```bash
|
|
tar -xzf proton-drive-linux-*-x86_64.tar.gz
|
|
proton-drive-linux-*-x86_64/install.sh
|
|
```
|
|
|
|
It puts the programs in `~/.local/bin`, the menu entry, icon, translations and shell completion in
|
|
`~/.local/share`, the service in `~/.config/systemd/user` and the tray's login entry in
|
|
`~/.config/autostart`, each pointing at `~/.local/bin`. Then open **Proton Drive for Linux** from
|
|
your applications menu. `--prefix DIR` installs somewhere else.
|
|
|
|
The system has to provide glibc 2.39 or newer (the binaries are built on Ubuntu 24.04), GTK 4.12,
|
|
libadwaita 1.5, WebKitGTK 6.0 and FUSE 3 with a setuid `fusermount3`; see
|
|
[Requirements](#requirements). `install.sh` checks the libraries first and names the packages to
|
|
install for each distribution. It refuses to install next to a package of this client, since the
|
|
two would run different versions of the service.
|
|
|
|
To update, download the new release and run its `install.sh`; a running service restarts on the new
|
|
version. Turn on **Preferences → General → Check for updates** to hear about new releases.
|
|
|
|
## Optional extras
|
|
|
|
The packages pull in what the client needs. These add features if you install them:
|
|
|
|
| Package | Adds |
|
|
|---|---|
|
|
| `exiftool` (`perl-image-exiftool`, `libimage-exiftool-perl`) | Thumbnails for camera RAW files |
|
|
| `ffmpeg` | Video thumbnails |
|
|
| `iso-codes` | Country names in your language on the Places map |
|
|
| `xdg-utils` | "Open Folder" in the tray, and the default file opener |
|
|
| `fzf` and a terminal (foot, kitty, alacritty, …) | `pdfs-prompt --fzf`, the search-as-you-type launcher |
|
|
| [AppIndicator extension](https://extensions.gnome.org/extension/615/appindicator-support/) (GNOME only) | The tray icon. KDE Plasma and most other desktops show it without help |
|
|
|
|
## First run
|
|
|
|
### With the desktop app
|
|
|
|
1. Open **Proton Drive** from your applications menu, or run `pdfs-app`.
|
|
2. Sign in with your Proton email and password, and your two-factor code if the account has one.
|
|
If Proton asks for a CAPTCHA (common on a VPN or a new network), the app shows the challenge in
|
|
a window and continues after you solve it.
|
|
3. The app enables and starts `proton-drive.service`. Your Drive appears at `~/ProtonDrive`.
|
|
|
|
The service belongs to your desktop session. It starts after you log in and stops when you log
|
|
out. To put the folder somewhere else, change **Preferences → General → Location**.
|
|
|
|
[Getting started](GETTING_STARTED.md) explains what to do next.
|
|
|
|
### With the command line
|
|
|
|
`pdfs login` stores the session but does not enable the service, so a setup that runs the service
|
|
another way stays untouched. Enable it yourself:
|
|
|
|
```bash
|
|
pdfs login # email, password, 2FA code
|
|
systemctl --user enable --now proton-drive.service
|
|
pdfs status # account, mount and queue state
|
|
```
|
|
|
|
`pdfs login` prints the address of the CAPTCHA page if Proton asks for one: open it in your
|
|
browser, solve it, then press Enter.
|
|
|
|
## Updating
|
|
|
|
| Installed from | Update with |
|
|
|---|---|
|
|
| COPR (Fedora) | `sudo dnf upgrade` |
|
|
| AUR | `paru -Syu`, or your AUR helper's equivalent |
|
|
| Nix flake | `nix flake update proton-drive-linux`, or change the pinned tag, then rebuild |
|
|
| Fedora Atomic | `rpm-ostree upgrade`, then reboot |
|
|
| `.deb`, release `.rpm` | Download the new release and install it over the old one |
|
|
| `.tar.gz` | Download the new release and run its `install.sh` |
|
|
|
|
The service switches to the new version the next time it starts. To switch at once:
|
|
|
|
```bash
|
|
systemctl --user restart proton-drive.service
|
|
```
|
|
|
|
With the `.deb`, the release `.rpm` or the `.tar.gz`, nothing tells you about a new release.
|
|
Turn on **Preferences → General → Check for updates**: the app asks GitHub once a day and shows a
|
|
banner over the sidebar when a newer version is out. The app never installs updates itself.
|
|
Packages that a package manager updates do not offer the setting. A package marks itself that way
|
|
by installing the empty file `share/proton-drive-linux/managed-updates` under the prefix of its
|
|
`bin/` directory, for example `/usr/share/proton-drive-linux/managed-updates`.
|
|
|
|
Coming from 2.8.0 or older, re-enable the service once. Those releases started it before the
|
|
desktop session was ready, and on KDE that crashes `ksecretd` at every login. Signing in again or
|
|
toggling **Start on login** does this as well:
|
|
|
|
```bash
|
|
systemctl --user reenable proton-drive.service
|
|
```
|
|
|
|
Database upgrades run by themselves and only move forward. A newer release's database does not
|
|
open in an older release, so going back to an older version means clearing the local database
|
|
(see [Troubleshooting](TROUBLESHOOTING.md#start-over-with-a-clean-local-state)).
|
|
|
|
## Uninstalling
|
|
|
|
> [!WARNING]
|
|
> Check that nothing is waiting to upload before you remove anything. `pdfs sync queue` must be
|
|
> empty. Changes that have not reached Proton Drive exist only on this computer.
|
|
|
|
1. Stop the service and sign out:
|
|
|
|
```bash
|
|
pdfs sync queue # must list nothing
|
|
systemctl --user disable --now proton-drive.service
|
|
pdfs logout # removes the session from the keyring
|
|
```
|
|
|
|
2. Remove the package:
|
|
|
|
| Installed from | Remove with |
|
|
|---|---|
|
|
| COPR (Fedora) | `sudo dnf remove proton-drive-linux`, then `sudo dnf copr remove narl-rs/proton-drive-linux` |
|
|
| Release `.rpm` | `sudo dnf remove proton-drive-linux` |
|
|
| `.deb` | `sudo apt remove proton-drive-linux` |
|
|
| AUR | `sudo pacman -R proton-drive-for-linux` (or the `-bin` or `-git` package) |
|
|
| NixOS | Remove the module and the flake input, then rebuild |
|
|
| Fedora Atomic | `rpm-ostree uninstall proton-drive-linux`, remove `/etc/yum.repos.d/proton-drive-linux.repo`, then reboot |
|
|
| `.tar.gz` | `~/.local/share/proton-drive-linux/install.sh --uninstall` |
|
|
|
|
Removing the package also stops the service of every logged-in user, in case step 1 was
|
|
skipped.
|
|
|
|
3. If you want no trace left, remove the local data:
|
|
|
|
```bash
|
|
rm -rf ~/.config/proton-drive-linux ~/.local/state/proton-drive-linux ~/.cache/proton-drive-linux
|
|
```
|
|
|
|
4. Sign the device out in your Proton account settings. If you no longer want this computer's
|
|
backups, remove it from **Computers** in the Proton Drive web app.
|
|
|
|
> [!CAUTION]
|
|
> Do not delete `~/ProtonDrive` while it is mounted. It is your Proton Drive, not a copy: every
|
|
> file deleted there is moved to the Proton Drive trash. Once the service is stopped, the folder
|
|
> is empty, and removing it is safe.
|
|
|
|
## Headless and server use
|
|
|
|
The packaged service starts with a desktop session. On a machine without one, run the service
|
|
directly or from your own systemd unit:
|
|
|
|
```bash
|
|
pdfs daemon # waits for a stored session, mounts, stays mounted
|
|
pdfs mount /srv/proton # mounts once at a given path, blocks until unmounted
|
|
```
|
|
|
|
Both still need a Secret Service provider for the session. On a server, run
|
|
`gnome-keyring-daemon --unlock` or KeePassXC's Secret Service integration inside the user's D-Bus
|
|
session.
|
|
|
|
## Build from source
|
|
|
|
### Requirements
|
|
|
|
| | Minimum |
|
|
|---|---|
|
|
| Architecture | Any that Rust and GTK support. Release packages are x86_64 only |
|
|
| Kernel | FUSE 3 (`fuse3` package, `/dev/fuse` available to your user) |
|
|
| GTK / libadwaita | GTK 4.12, libadwaita 1.5 (1.8 or newer gets the newest widgets) |
|
|
| WebKitGTK | 6.0, used only for the CAPTCHA page during sign-in |
|
|
| Secret Service | GNOME Keyring, KWallet, KeePassXC, or another provider of `org.freedesktop.secrets` |
|
|
| Rust | 1.96 |
|
|
|
|
The session is stored only in the Secret Service. Without a running provider, sign-in succeeds
|
|
but cannot be saved, and the service cannot start unattended.
|
|
|
|
### Build dependencies
|
|
|
|
**Debian / Ubuntu 24.04+**
|
|
|
|
```bash
|
|
sudo apt-get install -y pkg-config gettext libfuse3-dev libgtk-4-dev libadwaita-1-dev \
|
|
libwebkitgtk-6.0-dev libsecret-1-dev libdbus-1-dev
|
|
```
|
|
|
|
**Fedora 44+**
|
|
|
|
```bash
|
|
sudo dnf install -y cargo rust gettext pkgconf-pkg-config fuse3-devel gtk4-devel \
|
|
libadwaita-devel webkitgtk6.0-devel libsecret-devel dbus-devel glib2-devel
|
|
```
|
|
|
|
**Arch Linux**
|
|
|
|
```bash
|
|
sudo pacman -S --needed rust gettext pkgconf fuse3 gtk4 libadwaita webkitgtk-6.0 libsecret dbus
|
|
```
|
|
|
|
If your distribution ships a Rust older than 1.96, install a newer one with
|
|
[rustup](https://rustup.rs).
|
|
|
|
### Compile
|
|
|
|
```bash
|
|
git clone https://github.com/narrrl/proton-drive-linux.git
|
|
cd proton-drive-linux
|
|
cargo build --release --locked
|
|
po/build.sh target/locale # optional: compile the translations
|
|
```
|
|
|
|
The four programs are in `target/release/`: `pdfs`, `pdfs-app`, `pdfs-tray` and `pdfs-prompt`.
|
|
|
|
### Build a package from the working tree
|
|
|
|
**Arch Linux:**
|
|
|
|
```bash
|
|
cd packaging && makepkg -fi
|
|
```
|
|
|
|
<a id="build-an-rpm-locally"></a>**Fedora:**
|
|
|
|
```bash
|
|
sudo dnf install -y rpm-build
|
|
rpmbuild -bb packaging/proton-drive-linux.spec \
|
|
--define "git_dir $PWD" \
|
|
--define "_rpmdir $PWD/packaging/out" \
|
|
--define "_builddir $PWD/packaging/build" \
|
|
--define "_sourcedir $PWD" \
|
|
--define "_specdir $PWD/packaging" \
|
|
--define "_srcrpmdir $PWD/packaging/out"
|
|
sudo dnf install packaging/out/x86_64/proton-drive-linux-*.rpm
|
|
```
|
|
|
|
### Using a binary outside `/usr/bin`
|
|
|
|
The release tarball's `install.sh` does all of this for you (see
|
|
[Other distributions](#other-distributions)). For programs you built yourself: the service unit
|
|
starts `/usr/bin/pdfs daemon`. If you installed the programs somewhere else, for example
|
|
`~/.local/bin`, install the unit for your user and point it at your binary:
|
|
|
|
```bash
|
|
mkdir -p ~/.config/systemd/user
|
|
cp packaging/proton-drive.service ~/.config/systemd/user/
|
|
sed -i "s|^ExecStart=.*|ExecStart=$HOME/.local/bin/pdfs daemon|" \
|
|
~/.config/systemd/user/proton-drive.service
|
|
systemctl --user daemon-reload
|
|
```
|
|
|
|
To start the tray at login, copy `packaging/io.narl.proton-drive-linux-tray.desktop` to
|
|
`~/.config/autostart/`. For the entry in your applications menu, copy
|
|
`packaging/io.narl.proton-drive-linux.desktop` to `~/.local/share/applications/` and the icon
|
|
`packaging/io.narl.proton-drive-linux.svg` to `~/.local/share/icons/hicolor/scalable/apps/`.
|
|
|
|
## What the packages install
|
|
|
|
Every package installs the same files:
|
|
|
|
| Path | Purpose |
|
|
|---|---|
|
|
| `/usr/bin/pdfs` | Command-line client and background service |
|
|
| `/usr/bin/pdfs-app` | Desktop app |
|
|
| `/usr/bin/pdfs-tray` | Tray icon |
|
|
| `/usr/bin/pdfs-prompt` | Search launcher |
|
|
| `/usr/lib/systemd/user/proton-drive.service` | User service that keeps the drive mounted |
|
|
| `/etc/xdg/autostart/io.narl.proton-drive-linux-tray.desktop` | Starts the tray at login |
|
|
| `/usr/share/locale/*/LC_MESSAGES/pdfs.mo` | Translations |
|
|
|
|
The release tarball's `install.sh` puts the same files under `~/.local` instead of `/usr`, the
|
|
service in `~/.config/systemd/user` and the tray's login entry in `~/.config/autostart`. It keeps a
|
|
list of them in `~/.local/share/proton-drive-linux/installed-files` for `--uninstall`.
|