Library / SDK
rfjakob/gocryptfs avatar
rfjakob/gocryptfs

gocryptfs: an encrypted overlay filesystem and the 32 bytes it charges you

Encrypted overlay filesystem written in Go

4,778 stars310 forksGoMIT

At a glance

What is it?
gocryptfs mounts an encrypted directory as ordinary files, built on the go-fuse library and written in Go. Its design is deliberately boring in the ways that matter: a signed tag series, a regression tested CLI ABI, a master key printed at init, and a documented storage cost of 18 bytes per non-empty file plus 32 bytes per 4kB block.
Who is it for?
gocryptfs fits a Linux user who wants per-directory encryption with a real filesystem on top, who is prepared to keep the master key that gets printed at init, and who wants a documented on-disk format rather than an opaque container. It does not fit a Windows user looking for official support, because that platform is an independent C++ reimplementation, or a macOS user who needs stability rather than beta quality.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 4 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • rfjakob/gocryptfs4,778 ★ · +163
Star history
Repository2026-09-232026-11-15
rfjakob/gocryptfs4.6k4.8k

163 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Two directories, one mount, and a config file left on disk

The model is small enough to hold in your head. You have a directory of ciphertext and a directory where you want to read and write plaintext. Initialization writes a `gocryptfs.conf` into the ciphertext directory, then a mount makes the plaintext view appear at the second path:

sh
mkdir cipher plain
./gocryptfs -init cipher
./gocryptfs cipher plain

Reverse mode exists for the opposite direction, where the plaintext lives on disk and the encrypted copy is what you want to publish:

sh
mkdir cipher plain
./gocryptfs -reverse -init plain
./gocryptfs -reverse plain cipher

Underneath, the filesystem is FUSE, provided by the go-fuse library, which is why mounting is not self contained. The README is explicit that the `fuse` package from your distribution must be installed for mounting to work, and that precompiled binaries are offered for x86_64 Linux systems only. Every option is written down in `MANPAGE.md` rather than guessed at.

Keep a protected master-key backup

Initialization prints a master key, and the project's standing advice is to keep a copy of it somewhere safe. That single sentence carries most of the operational risk in this tool. Because the master key can unlock the data independently of the stored config, a damaged `gocryptfs.conf` or a forgotten password is not automatically a total loss, which is the failure mode that matters for a filesystem you cannot reformat your way out of. The same page also keeps the older principle in front of you: important data should have a backup, and an overlay filesystem is not a backup. Store the key off the encrypted volume. A copy of the key sitting next to the ciphertext it unlocks is not a backup.

Two build scripts, two crypto backends

Compiling from source needs a Go toolchain and one of two scripts. The README asks for Go 1.13 or higher, while the module file declares `go 1.26.0`, so a modern toolchain is what actually gets used today:

sh
git clone https://github.com/rfjakob/gocryptfs.git
cd gocryptfs
./build-without-openssl.bash

That script produces a static binary using the Go standard library crypto backend, which means no OpenSSL headers, no pkg-config, and one less moving part on a locked down machine. If you want the OpenSSL backend, which the README notes is faster on old CPUs lacking AES-NI, you install `libssl-dev gcc pkg-config` on Debian or Ubuntu, or `openssl-devel gcc pkg-config` on Fedora, and run `./build.bash` instead. The trade is real: the static build is easier to ship and audit, while the OpenSSL build is the one you want on hardware from before AES instructions were common. Both produce a normal command line binary that installs to `/usr/bin`.

`gocryptfs -speed` shows what your CPU can do

Cipher choice is measured rather than guessed. Running `gocryptfs -speed` benchmarks the ciphers your CPU can accelerate, and the sample output in the README comes from an Intel Core i5-3470 with AES acceleration, on a build dated 2021:

code
$ ./gocryptfs -speed
gocryptfs v2.2.0-beta1-5-g52b0444-dirty; go-fuse v2.1.1-0.20210825171523-3ab5d95a30ae; 2021-09-14 go1.17.1 linux/amd64
cpu: Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz; with AES acceleration
AES-GCM-256-OpenSSL              862.79 MB/s
AES-GCM-256-Go                   997.71 MB/s    (selected in auto mode)
AES-SIV-512-Go                   159.58 MB/s
XChaCha20-Poly1305-OpenSSL   729.65 MB/s
XChaCha20-Poly1305-Go            843.97 MB/s    (selected in auto mode)

Two ciphers are marked as selected in auto mode, and the striking number is how far behind AES-SIV-512 sits, at roughly a sixth of the AES-GCM throughput on the same machine. On CPUs without AES-NI the project routes through OpenSSL using a wrapper called `stupidgcm`, which the README credits with a 4x speedup over Go's builtin AES-GCM implementation. Treat the table as a shape rather than a promise for your own hardware, and run the command to see your own numbers. For bulk work there is also `./benchmark.bash`, which covers streaming write, extracting a Linux kernel tarball, recursive listing and deletion.

18 bytes per file and 32 bytes per block

The storage cost is written down as three numbers, which is more than most filesystem documentation gives you. Empty files take 0 bytes on disk, non-empty files carry an 18 byte header made of a 2 byte version and a 16 byte random file id, and every 4kB block adds 32 bytes of overhead for a 16 byte nonce and a 16 byte auth tag. That works out to well under one percent on a large file and rather more on a directory of small ones, which is where the header cost shows up. The file id is the mechanism behind a useful property: identical files encrypted twice get different ciphertext, because the id is random per file rather than derived from content. `Documentation/file-format.md` holds the fuller description if you need the byte layout, and the numbers above are the ones to check against your own file sizes before you commit to it.

macOS is beta and Windows is somebody else's port

Linux is the native platform, and that is not a hedge. macOS support is described as beta quality, which the README unpacks as most things working fine with an occasional problem, and it points at ticket 15 for the history while asking for a new ticket when you hit something current. Windows is not covered by this codebase at all: the page points to cppcryptfs, an independent C++ reimplementation, which also brings its own graphical interface. Another project, SiriKali, runs on Linux and macOS and supports gocryptfs from the outside. For scripting and inspection there are two Python tools that deliberately avoid FUSE, gocryptfs-inspect for decrypting files and file names, and gocryptfs-create-folder for encrypting a directory, which matters on a machine where you cannot mount anything. One more caution while you search for documentation: the README warns that the website gocryptfs.com is not affiliated with the project, and the official site is nuetzlich.net.

The test suite mounts filesystems, so it needs FUSE and root

Correctness here is argued with tests rather than prose. `./test.bash` runs the project's own suite, takes about a minute, and needs FUSE because it mounts several test filesystems while it works. The `stress_tests` directory holds tests that run indefinitely rather than finishing on their own. Beyond that, the xfstests suite has been ported to FUSE as the fuse-xfstests project, and gocryptfs passes the generic tests with one exception, with results written up in `Documentation/XFSTESTS.md`. The Makefile shows what the harder targets cost: `root_test` compiles and runs tests under `sudo`, and needs `TMPDIR=/var/tmp` because TestOverlay fails on tmpfs, which is the kind of detail that only shows up when someone wrote it down. The `ci` target prints `uname -a`, `go version`, `openssl version` and disk usage, then rebuilds with locked dependencies using `go mod vendor` and `GOPROXY=off` so a network fetch becomes a failure rather than a silent difference.

The v2 module path and a regression tested CLI ABI

Two contracts exist for code that calls gocryptfs from a script or another program, and they are separate from the Go API. `Documentation/CLI_ABI.md` holds the official stable ABI, and the README states that it is regression tested by the test suite, which makes it the part of the project you can build a wrapper against. The module path is `github.com/rfjakob/gocryptfs/v2`, so a v2 import is required to get the current code. The repository layout backs this up: `cli_args.go` and its test, `mount.go`, `init_dir.go`, `masterkey.go`, `fsck.go`, `info.go`, `daemonize.go` and `sendusr1.go` at the top level, with `ctlsock/` for the control socket, `gocryptfs-xray/` as a second binary that the Makefile installs alongside the main one, and `internal/` for the rest. Releases are at v2.6.1 from 10 August 2025, with commits landing more recently, on 28 October 2026. All tags from v0.4 onward are signed by the gocryptfs signing key, and the releases page explains how to check them.

Editorial conclusion

gocryptfs fits a Linux user who wants per-directory encryption with a real filesystem on top, who is prepared to keep the master key that gets printed at init, and who wants a documented on-disk format rather than an opaque container. It does not fit a Windows user looking for official support, because that platform is an independent C++ reimplementation, or a macOS user who needs stability rather than beta quality. Before you mount anything, check three things yourself: that the `fuse` package is installed for your distribution, that the FUSE daemon can start in your environment, and that you have somewhere safe for the master key outside the encrypted directory. Read the storage overhead figures against your own file sizes.

Frequently asked questions

what is gocryptfs?

gocryptfs is an encrypted overlay filesystem written in Go, built on the go-fuse FUSE library. You initialize a ciphertext directory, and mounting it gives you a plaintext view of the same files. It was inspired by EncFS and aims to fix EncFS's security issues, and it is released under the MIT licence.

how to install gocryptfs?

Distribution packages exist for most systems: apt install gocryptfs on Debian and Ubuntu, pacman -S gocryptfs on Arch, port install gocryptfs with MacPorts. Precompiled binaries for x86_64 Linux are on the github releases page, and the fuse package from your distribution must be installed for mounting to work.

how to use gocryptfs?

Create two directories, run ./gocryptfs -init cipher once to write gocryptfs.conf and print a master key, then mount with ./gocryptfs cipher plain. Add -reverse to encrypt in the other direction. Keep the printed master key somewhere safe: it lets you recover if the config file is damaged or the password is lost.

is gocryptfs secure?

The security design is written up as a separate document, and the project was audited in March 2017 by defuse.ca. It also states the old principle plainly: important data should have a backup, which is a reminder that an overlay filesystem is encryption, not versioning.

gocryptfs vs veracrypt?

The project does not publish that comparison. What it does publish is a benchmark page comparing gocryptfs with EncFS, where gocryptfs is described as as fast as EncFS in default mode and faster than EncFS paranoia mode. For Windows, gocryptfs points to cppcryptfs, an independent C++ reimplementation with its own GUI.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. rfjakob/gocryptfs on GitHub
Community

Where developers are discussing it

Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 1 in the last 30 days; newest first.

Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/rfjakob-gocryptfs.svg)](https://hysenlabs.com/projects/rfjakob-gocryptfs)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/rfjakob-gocryptfs.svg)](https://hysenlabs.com/projects/rfjakob-gocryptfs)

Was this useful?