Dokany: building Windows file systems in user mode with a FUSE wrapper

The problem Dokany solves on Windows

Writing a Windows file system normally means writing a kernel-mode device driver. The README is blunt about this: developing a device driver that works in kernel mode on Windows is extremely technical. Dokany's answer is to split the work. A kernel driver handles the plumbing, and your file system logic runs in a user-mode process where a crash takes down your process rather than the machine. The README states the intended audience directly: programmers who want to create their own file systems without writing device drivers. That covers backup and archive tools that want to mount a container as a drive, sync clients that expose a remote store as local files, and anyone porting a FUSE file system from Linux. It is not a general-purpose storage layer and it is not a replacement for NTFS on a system volume. It is a way to make a non-file data source look like files to Windows Explorer and to ordinary Win32 calls.

How the driver and the user-mode DLL hand requests back and forth

The layout is two components. dokan2.dll lives in user mode, dokan2.sys is the kernel-mode file system driver. Once the driver is installed, a program that uses the library (the README calls it a file system application) registers callback functions with the driver through the DLL. When a user program calls CreateFile, ReadFile or WriteFile, the request goes to the Windows I/O subsystem in kernel mode, which forwards it to dokan2.sys. The driver invokes the matching callback in your application. Your return values travel back the same path to the original caller. The README's example is Explorer opening a directory: the CreateFile with directory option reaches the driver, the driver calls your CreateFile callback, and your result is what Explorer sees. The driver is a proxy, and that is the whole design. The trade-off is a round trip across the user/kernel boundary for every operation, which is why the release notes for v2 emphasize threading and memory pool changes rather than raw single-call latency.

Installing Dokany and mounting the memfs sample

The README gives three install routes: the GitHub release page for the signed build, `choco install dokany2`, or `winget install dokan-dev.dokany`. The package manager commands are the shortest path on a development machine.

choco install dokany2

or

winget install dokan-dev.dokany

After the installer runs, `dokanctl.exe` is the control program, and the README lists it as MIT licensed, separate from the LGPL core. The samples directory holds `dokan_memfs` and `dokan_mirror`, and the README points at `dokan_memfs` as the place to start. The repository also contains `samples/memfs_test.ps1` and `samples/mirror_test.ps1` for exercising them. What you should see after running a sample is a new drive letter in Explorer whose contents come from the sample's in-memory store rather than from disk. The README does not document a command-line flag set for the samples, so read the sample source before assuming options. For manual installation the README defers to the installation wiki page rather than reproducing the steps.

The FUSE wrapper, and what porting actually costs

The repository has a `dokan_fuse/` tree and builds `dokanfuse2.dll`. The README says the FUSE wrapper helps you port your FUSE file systems without changes. Treat that as the goal, not a guarantee. The wrapper lets a FUSE file system compile and run against Dokany's callbacks, but the underlying platform is still Windows: path semantics, case sensitivity, permission checks and the set of operations Windows actually issues all come from the Windows side. A FUSE file system that leans on POSIX-specific behaviour will still need attention. The wrapper is most valuable for the common case, a file system built around the standard FUSE callback table with no platform-specific shortcuts. If your FUSE code calls into libfuse internals beyond that table, budget time for the port rather than assuming a rebuild is enough.

API churn is the real upgrade cost

The README is unusually candid here. Since version 0.8.0, Dokany broke compatibility with the Dokan API. The API changed again in 1.1.0 and again in 2.0.0, and the README links separate wiki pages for updating a 1.0.0 application to 1.1.0 and a 1.1.0 application to 2.0.0. That means an application written against an older Dokany is not a drop-in rebuild against the current library. The wiki pages exist precisely because the migration is manual. The benchmark section in the README compares v1.5.1.1000 against v2.0.3.1000 on the `memfs` sample, run five times in an idle environment, with the full results in a linked spreadsheet. The README attributes the gains to better threading and memory pool work in v2 and expects concurrent scenarios to benefit most. Those numbers come from the project's own benchmark on a sample file system, so they describe the library's overhead, not your file system's throughput. The practical consequence: upgrading Dokany is a code change, not just a dependency bump, and you should plan it that way.

Licence split and what it means for shipping

Dokany contains both LGPL and MIT licensed programs. Per the README, the user-mode library `dokan2.dll`, the driver `dokan2.sys`, the network library `dokannp2.dll`, the FUSE library `dokanfuse2.dll` and the installer `DokanSetup.exe` are LGPL. The control program `dokanctl.exe` and the samples `mirror.exe` and `memfs.exe` are MIT. The license files are `license.lgpl.txt` and `license.mit.txt` at the repository root. The practical shape of this is that the MIT parts are permissive while the components your file system actually links against and installs carry LGPL obligations. The README does not spell out what those obligations are for a closed-source product, and this article is not legal advice. If you plan to redistribute Dokany with a proprietary application, the question to put to counsel is specifically about dynamic linking to `dokan2.dll` and bundling `dokan2.sys`, not about the project as a whole.

Where Dokany is the wrong choice

Two limits stand out. First, the platform list. The README names Windows Server 2022, 2019, 2016, 2012 (R2) and 2008 R2 SP1, plus Windows 11, 10, 8.1, 8 and 7 SP1, on x86, x64, ARM and ARM64. If your target is outside that set, the README offers nothing. Second, the kernel driver. Dokany installs a signed kernel-mode component, and the README documents installation but says nothing about rollback or clean removal beyond the control program's existence. If your deployment environment forbids kernel drivers, or if you cannot get a driver installed and later removed cleanly on user machines, Dokany is the wrong tool regardless of how well the user-mode API fits. A pure user-mode alternative such as a virtual file system that does not mount a drive letter avoids the driver entirely, at the cost of not appearing as a normal file system to arbitrary Windows programs.

Dokany compared with WinFsp

The obvious alternative in this space is WinFsp, a separate Windows user-mode file system framework. The difference in approach is in what you write against. Dokany's native API is its own callback set, and the FUSE wrapper is an add-on layer for porting. WinFsp is built around FUSE compatibility from the start and also exposes its own native API. For a new project, that means the FUSE-facing code you write is the primary interface rather than a compatibility shim. For an existing Dokany application, the migration is a rewrite of the callback layer, not a configuration change. Dokany's advantage in the comparison is the explicit FUSE wrapper and the sample set in the repository, which give you a working file system to read before you write your own. Neither project's README settles which is faster for your workload; both publish their own numbers, and the only useful measurement is one you run against your own callbacks.

Editorial conclusion

Adopt Dokany if you need to expose a custom store as a drive letter on Windows and can live with the LGPL terms on dokan2.dll and dokan2.sys, or if you are porting an existing FUSE file system and want to reuse its callbacks. Do not adopt it if you need a documented rollback path for the kernel driver, if your target is an older Windows release outside the listed set, or if you cannot accept a kernel-mode component in your deployment. Verify first that the signed driver for your architecture is present in the release you plan to ship, that your installer handles driver removal rather than leaving it behind, and that the API level you compile against matches the runtime your users have.

Frequently asked questions

Official sources

1. dokan-dev/dokany on GitHub
2. Issues
3. Project website
4. README
5. Releases