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-driveCLI binary — install it withprotonfs install-drive(below), or supply your own onPATH/ viaPROTONFS_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, 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.
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.
License
PolyForm Noncommercial 1.0.0 — free for noncommercial use with attribution; contact the author for commercial use.
1 maintainer
Release files for protonfs 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| protonfs-0.3.0.tar.gz | 58.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| protonfs-0.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 102.1 kB
Release files / protonfs-0.3.0.tar.gz
| Download URL | protonfs-0.3.0.tar.gz |
|---|---|
| Size | 58.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fb668dd5d3c1e1deb83afa70ab8762a206e7bc5684775d6ed6140c6422e76861
|
|
BLAKE2b-256 checksum How to use checksums |
5155d26929d1aa4be08f228f2bf133eb774cf2983a219ed1c94ec9e06b5f877a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency logRelease files / protonfs-0.3.0-py3-none-any.whl
| Download URL | protonfs-0.3.0-py3-none-any.whl |
|---|---|
| Size | 43.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e11db08082caca0805db69b65c008cd96bd7dd397294cf99e504e08910806276
|
|
BLAKE2b-256 checksum How to use checksums |
82bd4f983b1a516042d97eebad432d0629ea165ec609fb95b81a9625f273c188
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency log
