WinBtrfs - an open-source btrfs driver for Windows
LGPL-3.0 License
WinBtrfs is a Windows driver for the next-generation Linux filesystem Btrfs. A reimplementation from scratch, it contains no code from the Linux kernel, and should work on any version from Windows XP onwards. It is also included as part of the free operating system ReactOS.
If your Btrfs filesystem is on a MD software RAID device created by Linux, you will also need WinMD to get this to appear under Windows.
See also Quibble, an experimental bootloader allowing Windows to boot from Btrfs, and Ntfs2btrfs, a tool which allows in-place conversion of NTFS filesystems.
First, a disclaimer:
You use this software at your own risk. I take no responsibility for any damage it may do to your filesystem. It ought to be suitable for day-to-day use, but make sure you take backups anyway.
Everything here is released under the GNU Lesser General Public Licence (LGPL); see the file LICENCE for more info. You are encouraged to play about with the source code as you will, and I'd appreciate a note ([email protected]) if you come up with anything nifty.
See at the end of this document for copyright details of third-party code that's included here.
mkbtrfs.exe
and ubtrfs.dll
free_space_cache
)To install the driver, download and extract the latest release, right-click btrfs.inf, and choose Install. The driver is signed, so should work out of the box on modern versions of Windows.
If you using Windows 10 or 11 and have Secure Boot enabled, you may have to make a Registry change in order for the driver to be loaded - see below. It's easier though just to turn off Secure Boot in your BIOS, unless you have a particular need for it. Bear in mind that Windows 11 soft-requires Secure Boot to be installed, but will work fine afterwords with it turned off.
WinBtrfs is also available on the following package managers:
choco install winbtrfs
scoop bucket add nonportable
scoop install winbtrfs-np -g
If you want to uninstall, from a command prompt run:
RUNDLL32.EXE SETUPAPI.DLL,InstallHinfSection DefaultUninstall 132 btrfs.inf
You may need to give the full path to btrfs.inf.
You can also go to Device Manager, find "Btrfs controller" under "Storage volumes", right click and choose "Uninstall". Tick the checkbox to uninstall the driver as well, and let Windows reboot itself.
If you need to uninstall via the registry, open regedit and set the value of HKLM\SYSTEM\CurrentControlSet\services\btrfs\Start to 4, to disable the service. After you reboot, you can then delete the btrfs key and remove C:\Windows\System32\drivers\btrfs.sys.
To compile with Visual C++ 2019, open the directory and let CMake do its thing. If you have the Windows DDK installed correctly, it should just work.
To compile with GCC on Linux, you will need a cross-compiler set up, for either
i686-w64-mingw32
or x86_64-w64-mingw32
. Create a build directory, then use
either mingw-x86.cmake
or mingw-amd64.cmake
as CMake toolchain files to
generate your Makefile.
The user mappings are stored in the registry key HKLM\SYSTEM\CurrentControlSet\services\btrfs\Mappings. Create a DWORD with the name of your Windows SID (e.g. S-1-5-21-1379886684-2432464051-424789967-1001), and the value of your Linux uid (e.g. 1000). It will take effect next time the driver is loaded.
You can find your current SID by running wmic useraccount get name,sid
.
Similarly, the group mappings are stored in under GroupMappings. The default entry maps Windows' Users group to gid 100, which is usually "users" on Linux. You can also specify user SIDs here to force files created by a user to belong to a certain group. The setgid flag also works as on Linux.
Note that processes running under User Access Control tokens create files as the BUILTIN\Administrators SID (S-1-5-32-544), rather as a user account.
The driver will passthrough Linux metadata to recent versions of LXSS, but you
will have to let Windows know that you wish to do this. From a Bash prompt on
Windows, edit /etc/wsl.conf
to look like the following:
[automount]
enabled = true
options = "metadata"
mountFsTab = false
It will then take effect next time you reboot. Yes, you should be able to chroot into an actual Linux installation, if you wish.
The DLL file shellbtrfs.dll provides the GUI interface, but it can also be used with rundll32.exe to carry out some tasks from the command line, which may be useful if you wish to schedule something to run periodically.
Bear in mind that rundll32 provides no mechanism to return any error codes, so any of these commands may fail silently.
rundll32.exe shellbtrfs.dll,CreateSubvol <path>
rundll32.exe shellbtrfs.dll,CreateSnapshot <source> <destination>
rundll32.exe shellbtrfs.dll,ReflinkCopy <source> <destination>
This also accepts wildcards, and any number of source files.
The following commands need various privileges, and so must be run as Administrator to work:
rundll32.exe shellbtrfs.dll,SendSubvol <source> [-p <parent>] [-c <clone subvol>] <stream file>
The -p and -c flags are as btrfs send
on Linux. You can specify any number of
clone subvolumes.
rundll32.exe shellbtrfs.dll,RecvSubvol <stream file> <destination>
rundll32.exe shellbtrfs.dll,StartScrub <drive>
rundll32.exe shellbtrfs.dll,StopScrub <drive>
On the releases page, there's zip files to download containing the PDBs. Or you can try the symbols server http://symbols.burntcomma.com/ - in windbg, set your symbol path to something like this:
symsrv*symsrv.dll*C:\symbols*http://msdl.microsoft.com/download/symbols;symsrv*symsrv.dll*C:\symbols*http://symbols.burntcomma.com
The driver assumes that all filenames are encoded in UTF-8. This should be the default on most setups nowadays - if you're not using UTF-8, it's probably worth looking into converting your files.
For the later versions of Windows 10, Microsoft introduced more onerous requirements for signing, which seemingly aren't available for open-source drivers.
To work around this, go to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CI\Policy
in Regedit,
create a new DWORD value called UpgradedSystem
and set to 1, and reboot.
Or you could always just turn off Secure Boot in your BIOS settings.
This is something Microsoft hardcoded into LXSS, presumably to stop people hosing
their systems by running mkdir /mnt/c/WiNdOwS
.
With the shell extension installed, right-click the drive in Explorer, click Properties, and go to the Btrfs tab. There should be a button which allows you to change the drive letter.
In Regedit, try deleting the relevant entries in HKEY_LOCAL_MACHINE\SYSTEM\MountedDevices
,
then rebooting.
Use the included command line program mkbtrfs.exe. We can't add Btrfs to Windows' own
dialog box, unfortunately, as its list of filesystems has been hardcoded. You can also
run format /fs:btrfs
, if you don't need to set any Btrfs-specific options.
If Windows' Format dialog box refuses to appear, try running format.com with the /fs
flag, e.g. format /fs:ntfs D:
.
Synology seems to use LVM for its block devices. Until somebody writes an LVM driver for Windows, you're out of luck.
Thecus uses Linux's MD raid for its block devices. You will need to install WinMD as well.
Make sure that you have KB3033929 installed. Or consider installing from an "escrow" ISO which includes all updates.
Paragon's filesystem-reading software is known to disable automount. Disable or
uninstall Paragon, then re-enable automount by running diskpart
and typing
automount enable
.
On very old versions of Windows (XP, Server 2003?), Windows ignores Linux partitions
entirely. If this is the case for you, try running fdisk
on Linux and changing your
partition type from 83 to 7.
v1.9 (2024-03-15):
v1.8.2 (2023-01-10):
v1.8.1 (2022-08-23):
v1.8 (2022-03-12):
v1.7.9 (2021-10-02):
v1.7.8.1 (2021-06-13):
v1.7.8 (2021-06-09):
inode_cache
had been usedv1.7.7 (2021-04-12):
v1.7.6 (2021-01-14):
v1.7.5 (2020-10-31):
v1.7.4 (2020-08-23):
v1.7.3 (2020-05-24):
v1.7.2 (2020-04-10):
v1.7.1 (2020-03-02):
v1.7 (2020-02-26):
case=dir
option setv1.6 (2020-02-04):
v1.5 (2019-11-10):
v1.4 (2019-08-31):
v1.3 (2019-06-10):
v1.2.1 (2019-05-06):
v1.2 (2019-05-05):
v1.1 (2018-12-15):
v1.0.2 (2018-05-19):
v1.0.1 (2017-10-15):
v1.0 (2017-09-04):
free_space_cache
)v0.10 (2017-05-02):
btrfs check
v0.9 (2017-03-05):
v0.8 (2016-12-30):
btrfs fi usage
v0.7 (2016-10-24):
raid56
)v0.6 (2016-08-21):
v0.5 (2016-07-24):
v0.4 (2016-05-02):
v0.3 (2016-03-25):
btrfs check
v0.2 (2016-03-13):
CcCopyRead
v0.1 (2016-02-21):
WinBtrfs has three levels of debug messages: errors and FIXMEs, warnings, and traces.
The release version of the driver only displays the errors and FIXMEs, which it logs
via DbgPrint
. You can view these messages via the Microsoft program DebugView, available
at https://technet.microsoft.com/en-gb/sysinternals/debugview.
If you want to report a problem, it'd be of great help if you could also attach a full debug log. To do this, you will need to use the debug versions of the drivers; copy the files in Debug\x64 or Debug\x86 into x64 or x86. You will also need to set the registry entries in HKLM\SYSTEM\CurrentControlSet\Services\btrfs:
DebugLogLevel
(DWORD): 0 for no messages, 1 for errors and FIXMEs, 2 for warnings also,LogDevice
(string, optional): the serial device you want to output to, such as\Device\Serial0
. This is probably only useful on virtual machines.LogFile
(string, optional): the file you wish to output to, if LogDevice
isn't set.The driver will create subkeys in the registry under HKLM\SYSTEM\CurrentControlSet\Services\btrfs
for each mounted filesystem, named after its UUID. If you're unsure which UUID refers to which
volume, you can check using btrfs fi show
on Linux. You can add per-volume mount options to this
subkey, which will take effect on reboot. If a value is set in the key above this, it will use this
by default.
Ignore
(DWORD): set this to 1 to tell the driver not to attempt loading this filesystem. With the
Readonly
flag, this is probably redundant.
Readonly
(DWORD): set this to 1 to tell the driver not to allow writing to this volume. This is
the equivalent of the ro
flag on Linux.
Compress
(DWORD): set this to 1 to tell the driver to write files as compressed by default. This is
the equivalent of the compress
flag on Linux.
CompressForce
(DWORD): set this to 1 to force compression, i.e. to ignore the nocompress
inode
flag and even attempt compression of incompressible files. This isn't a good idea, but is the equivalent
of the compress-force
flag on Linux.
CompressType
(DWORD): set this to 1 to prefer zlib compression, 2 to prefer lzo compression, or 3
to prefer zstd compression. The default is 0, which uses zstd or lzo compression if the incompat flags
are set, and zlib otherwise.
FlushInterval
(DWORD): the interval in seconds between metadata flushes. The default is 30, as on Linux -
the parameter is called commit
there.
ZlibLevel
(DWORD): a number between -1 and 9, which determines how much CPU time is spent trying to
compress files. You might want to fiddle with this if you have a fast CPU but a slow disk, or vice versa.
The default is 3, which is the hard-coded value on Linux.
MaxInline
(DWORD): the maximum size that will be allowed for "inline" files, i.e. those stored in the
metadata. The default is 2048, which is also the default on modern versions of Linux - the parameter is
called max_inline
there. It will be clipped to the maximum value, which unless you've changed your node
size will be a shade under 16 KB.
SubvolId
(QWORD): the ID of the subvolume that we will attempt to mount as the root. If it doesn't
exist, this parameter will be silently ignored. The subvolume ID can be found on the inode property
sheet; it's in hex there, as opposed to decimal on the Linux tools. The default is whatever has been set
via btrfs subvolume set-default
; or, failing that, subvolume 5. The equivalent parameter on Linux is
called subvolid
.
SkipBalance
(DWORD): set to 1 to tell the driver not to attempt resuming a balance which was running
when the system last powered down. The default is 0. The equivalent parameter on Linux is skip_balance
.
NoPNP
(DWORD): useful for debugging only, this forces any volumes to appear rather than exposing them
via the usual Plug and Play method.
ZstdLevel
(DWORD): Zstd compression level, default 3.
NoTrim
(DWORD): set this to 1 to disable TRIM support.
AllowDegraded
(DWORD): set this to 1 to allow mounting a degraded volume, i.e. one with a device
missing. You are strongly advised not to enable this unless you need to.
NoRootDir
(DWORD): if you have changed your default subvolume, either natively or by a registry option,
there will be a hidden directory called $Root which points to where the root would normally be. Set this
value to 1 to prevent this appearing.
NoDataCOW
(DWORD): set this to 1 to disable copy-on-write for new files. This is the equivalent of the
nodatacow
flag on Linux.
I'd appreciate any feedback you might have, positive or negative: [email protected].
This code contains portions of the following software:
Copyright (C) 1995-2017 Jean-loup Gailly and Mark Adler
This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.
Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:
WinBtrfs contains portions of an early version of lzo, which is copyright 1996 Markus Oberhumer. Modern versions are licensed under the GPL, but this was licensed under the LGPL, so I believe it is okay to use.
Copyright (c) 2016-present, Facebook, Inc. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name Facebook nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
https://github.com/BLAKE2/BLAKE2 (public domain)
https://github.com/amosnier/sha-2 (public domain)