pygocryptfs

A Python toolkit for gocryptfs v2 encrypted filesystems, inspired by pycryptomator.

Provides full programmatic and shell-based access to a gocryptfs vault without needing the FUSE driver installed.

Requirements

• Python ≥ 3.10
• pycryptodome or pycryptodomeX

pip install pycryptodome

Supported feature flags

Interactive shell

python -m pygocryptfs /path/to/vault
# or with explicit password
python -m pygocryptfs --password mypassword /path/to/vault

The shell understands these commands:

Shell wildcards (*, ?) are supported for all commands.

ls sort specifiers

Single-command mode

python -m pygocryptfs --password secret /vault ls /
python -m pygocryptfs --password secret /vault decrypt /secret.txt /tmp/out.txt
python -m pygocryptfs --password secret /vault encrypt /tmp/myfile.txt /

Initialise a new vault

python -m pygocryptfs --init --password mypassword /path/to/new/vault

Print / backup the master key

# Print in hex (default)
python -m pygocryptfs --password secret --print-key     /vault
# Print in base64
python -m pygocryptfs --password secret --print-key b64 /vault
# Print in ASCII85
python -m pygocryptfs --password secret --print-key a85 /vault

Change the vault password

python -m pygocryptfs --password oldpass --change-password /vault

Programmatic API

from pygocryptfs import Vault, init_vault, backupDirIds

# Open an existing vault
v = Vault('/path/to/vault', password='secret')

# List root
v.ls(['/'])

# Decrypt a file
v.decryptFile('/documents/report.pdf', '/tmp/report.pdf', force=True)

# Encrypt a file
v.encryptFile('/tmp/photo.jpg', '/photos/photo.jpg')

# Walk the virtual filesystem
for root, dirs, files in v.walk('/'):
    print(root, dirs, files)

# Create a directory
v.mkdir('/new_folder')

# Move / rename
v.mv('/old_name.txt', '/new_name.txt')

# Remove
v.remove('/unwanted.txt')
v.rmtree('/old_folder')

# Backup directory IVs
backupDirIds('/path/to/vault', '/tmp/diriv_backup.zip')

Package structure

pygocryptfs/
├── __init__.py       # public API: Vault, init_vault, backupDirIds
├── __main__.py       # CLI entry point
├── gocryptfs.py      # Vault class + all crypto logic
└── gcshell.py        # Interactive shell (GCShell)

License

MIT License – see source files for copyright notices.