Skip to main content

protonfs — version, links, test/coverage/lint/docs status, Python support and build matrix

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 does not need version history, just somewhere durable to live and a way to fetch it back on demand.

Why protonfs

  • Conflict-aware push/pull over a local sync manifest (.protonfs/index.json), so each machine knows what it has, what the remote has, and what diverged.
  • Verify-before-delete offload -- reclaim local disk space only for files proven byte-for-byte present on Drive (via Proton's plaintext size/digest, not the encrypted size).
  • Headless-first: a keyring/session-bus bootstrap and a doctor that diagnoses and repairs the Secret Service, so it works over SSH with no desktop.
  • Durable by design: atomic index writes, an advisory repo lock, resumable refresh under API throttling, and SHA-512-pinned proton-drive binaries.
  • A frozen 1.0 command surface: every command, option, exit code, and config key is a documented, stable contract.

Requirements

  • Python >= 3.9
  • The proton-drive CLI binary -- install it with protonfs install-drive, 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)

Quickstart

cd ~/my-project
protonfs setup             # init .protonfs/, prompt for the Drive path to sync into
protonfs push --dry-run    # preview what would upload (changes nothing)
protonfs push              # upload local files to Drive
protonfs status            # confirm everything is in sync (exit 0 == clean)

On a headless server, run protonfs doctor --fix before auth login to prepare the keyring first.

More: full documentation · task guide · command reference.

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.

Scoping what gets synced

.protonfs/ignore is a denylist in gitignore syntax, scoped to a repo and independent of its own .gitignore — patterns like *.tmp or core.* are excluded from every push/pull/refresh/status/ls.

Syncing only matching files

Sometimes you want the opposite: sync only files of certain types (e.g. only simulation dumps, ignoring notes/scratch/logs). Add an allowlist at .protonfs/include, in the same gitignore syntax:

# .protonfs/include
*.ev
*.sink
*_[0-9][0-9][0-9][0-9][0-9]

When .protonfs/include exists and has at least one active (non-blank, non-comment) line, a file is synced only if it matches one of its patterns — and still not matched by .protonfs/ignore, which always wins over include. If include is absent, or every line in it is blank/commented out, behaviour is unchanged: everything not matched by ignore is synced.

Patterns are plain gitignore file patterns, matched only against file paths. You don't need !*/ or dir/** tricks here — directories are always descended into regardless of include/ignore, so a plain *.ev reaches files at any depth.

If you'd rather not add a second file, the same "only these files" behaviour can be expressed with .protonfs/ignore alone, but it needs a double-negation recipe and has two sharp edges:

# .protonfs/ignore -- sync only *.ev/*.sink and files ending in a 5-digit run number
*
!*/
!*_[0-9][0-9][0-9][0-9][0-9]
!*.ev
!*.sink
*mload*/**
  • !*/ is mandatory: once a parent directory is excluded, a later re-include pattern (like !*.ev) cannot resurrect files under it — gitignore semantics never descend into an already-excluded directory to re-evaluate its contents.
  • to exclude a whole subtree again (here, anything under a *mload* directory) you must write dir/**, not dir/ — a trailing-slash directory pattern does not match the files beneath it when tested against file paths the way protonfs's matcher does.

.protonfs/include avoids both pitfalls, which is why it exists as a separate first-class file rather than only being achievable via ignore.

Releasing (maintainers)

See CHANGELOG.md for release history and upgrade notes. To upgrade an installation: pip install --upgrade protonfs, then protonfs upgrade to bring the proton-drive binary and any repo state current (docs: Upgrading).

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 (the ghtools workflow runs the tests before its release job creates 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.

Metadata

Release files for protonfs 3.2.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 3.2.0
File Size Uploaded Provenance Actions
protonfs-3.2.0.tar.gz 521.7 kB With provenance Details for protonfs-3.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for protonfs 3.2.0
File Interpreter ABI Platform Actions
protonfs-3.2.0-py3-none-any.whl Python 3 none any Details for protonfs-3.2.0-py3-none-any.whl

Total release size: 768.2 kB

Release files / protonfs-3.2.0.tar.gz

Download URL protonfs-3.2.0.tar.gz
Size 521.7 kB
Tags Source
SHA-256 checksum
How to use checksums
f2794a881d0015c3467985d7d16f864bf862df17e2a171f98895db83ae1bdbff
BLAKE2b-256 checksum
How to use checksums
d21c64b12c8611c2ce1a7ffa01cf45047aedbf0b504075402c6ead3b728927c3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 24, 2026.

Transparency log

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

Download URL protonfs-3.2.0-py3-none-any.whl
Size 246.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2faea2643f6836321bf4b4673ef2c56b27b81d80fa6dd2d3703e6155fd6eda72
BLAKE2b-256 checksum
How to use checksums
3e94b292ebc7487752b1b414b3148850aa190f1ee65b388afc0901d3ec8b77e6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 24, 2026.

Transparency log

Security for protonfs 3.2.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for protonfs-3.2.0.tar.gz

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 Oct 24, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page