protonfs

Sync a local directory tree with Proton Drive, via the official Proton Drive CLI, with conflict-aware push/pull and a local sync manifest.

Originally built to replace git-lfs as the storage layer for large, write-once simulation output — data that doesn't need version history, just somewhere durable to live and a way to fetch it back on demand.

The command surface (setup, status, ls, push, pull, rm, restore, refresh, install-drive, auth) is implemented — see src/protonfs/cli.py.

Requirements

Python >= 3.9
The proton-drive CLI binary — install it with protonfs install-drive (below), or supply your own on PATH / via PROTONFS_DRIVE_BIN.

Install

pip install protonfs
protonfs install-drive     # downloads + SHA-512-verifies the official proton-drive binary
protonfs auth login        # opens a URL to authenticate (passthrough to proton-drive)

install-drive detects your platform (linux-x64/arm64, macOS x64/arm64 — all checksum-pinned), requires AVX2 for the linux-x64 prebuilt (with an instructive fallback otherwise), and never installs a binary whose SHA-512 does not match the pinned checksum. Override the version with PROTONFS_DRIVE_VERSION and the expected checksum with PROTONFS_DRIVE_SHA512. On Windows, use WSL — native Windows is out of scope for 1.0.

Headless Linux (SSH, no desktop)

proton-drive keeps its session in the OS keyring, which on Linux means the freedesktop Secret Service reached over the D-Bus session bus. An SSH login has neither, which produces two failures that look like bugs in Proton Drive but are really a missing environment:

Cannot autolaunch D-Bus without X11 $DISPLAY          # no session bus at all
Cannot create an item in a locked collection          # bus exists; the keyring is sealed

The second one is the nastier of the two: if the machine has ever had a graphical login, ~/.local/share/keyrings/login.keyring exists, is the default collection, and is locked with a password you cannot type over SSH — so auth login completes the whole browser flow and only then fails to save the session.

protonfs handles both for you. Every command that shells out to proton-drive first reuses (or starts, and caches) a session bus, and runs gnome-keyring-daemon against a protonfs-owned keyring directory so it never has to unlock the sealed system keyring. To check a host:

protonfs doctor          # binary, session bus, Secret Service, and a real keyring write test
protonfs doctor --fix    # ...and repair what it can

Requires dbus-launch, gnome-keyring-daemon and gdbus (packages dbus/dbus-x11, gnome-keyring, glib2). No root needed. To run the proton-drive binary by hand in the same environment, use eval "$(protonfs shell-init)".

Escape hatches: PROTONFS_KEYRING_PASSWORD supplies your own keyring password instead of the generated one, and PROTONFS_NO_KEYRING_BOOTSTRAP=1 turns all of this off if you'd rather manage the environment yourself.

Releasing (maintainers)

Merges to main auto-tag a release, but only after the full test matrix passes with an 80% coverage floor on the exact commit being tagged (auto-release.yml calls the CI workflow before creating the tag). Before milestone or manual tags, also run the live suite against a disposable Drive directory — it exercises real uploads/downloads that CI never can:

PROTONFS_TEST_REMOTE=/my-files/test .github/scripts/release_gate.sh

License

PolyForm Noncommercial 1.0.0 — free for noncommercial use with attribution; contact the author for commercial use.

Environment
- Console
License
- Other/Proprietary License
Operating System
- MacOS
- POSIX :: Linux
Programming Language
- Python :: 3

Release files for protonfs 0.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for protonfs 0.14.0
File	Size	Uploaded
protonfs-0.14.0.tar.gz	102.7 kB	Jul 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for protonfs 0.14.0
File	Interpreter	ABI	Platform	Reset
protonfs-0.14.0-py3-none-any.whl 64.5 kB Jul 16, 2026	Python 3	none	any	Details

Total release size: 167.1 kB

Release files / protonfs-0.14.0.tar.gz

Download URL	protonfs-0.14.0.tar.gz
Size	102.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`8f93d57af73de813f64012de4e35fd2696d98da7af332ccae2452b4a681b9d58`
BLAKE2b-256 checksum How to use checksums	`9d44c6ecd07064fd09b6806f2d14072d8c11530e3f4b01a3e6ffc2a82582c713`
Upload date	Jul 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Release files / protonfs-0.14.0-py3-none-any.whl

Download URL	protonfs-0.14.0-py3-none-any.whl
Size	64.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`34df53a01e16aa2b1194e243722e8fb12b1827bf0a20850870ae0128b6e64a68`
BLAKE2b-256 checksum How to use checksums	`b1e866a38efafbd6eb2f3e326eeab6202d56aa5694b887d7a5624f6de1eae378`
Upload date	Jul 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`