Windows (Beta) Usage Guide

Starting from JuiceFS EE 5.2, JuiceFS supports running on Windows. Please note that the Windows client is currently in Beta phase, make sure you read the following instructions carefully.

Runtime Dependencies

Windows does not natively support FUSE. To run JuiceFS on Windows, you must install WinFsp, an open-source implementation of FUSE for Windows. Before running JuiceFS.exe, download and install the latest WinFsp release from its GitHub repository.

Mount Modes

JuiceFS on Windows supports both foreground and background mounting, just like on Linux:

• Background mode. In this mode, the file system is mounted under the SYSTEM account. If you want the drive to be visible to all users on your machine, choose background mode. Background mounts require administrator privileges.
• Foreground mode. The file system is mounted under your current user session and is only visible to that user.

By default, the Windows version of JuiceFS uses the background mode.

note

If you choose foreground mounting, the mounted file system is only visible to the current user. This means that if you run the mount command as Administrator (for example, in an elevated Terminal or PowerShell), other users cannot access that mount.

Mount Types

On Windows, JuiceFS can register the file system in two ways:

1. Network file system：The mounted volume appears as a network filesystem. The OS applies network-I/O optimizations for better performance. This is the default type.
2. Local Device：The file system is registered as a local device. Use this mode if you need to mount to a non-drive-letter path or share the mounted drive. Enable it with --mount-as-local。

Permission Model Differences

Windows and Linux use fundamentally different permission models. Windows manages file and directory permissions using access control lists (ACLs), while Linux uses the POSIX permission model. JuiceFS stores metadata using the POSIX model. Therefore, some behavioral differences may occur during the permission mapping and conversion process.

For example, when creating a new file on Windows, the file permissions may be determined by the Security Descriptor used at creation time as well as the parent directory. If you want all newly created files to have a fixed set of permissions, you can use the --create-perm=xxx option when mounting (for example, --create-perm=0755).

UID & GID Mapping

On Windows, user IDs and groups are represented as SIDs, which are strings like S-1-5-32-544. When in use, JuiceFS converts Windows SIDs to UIDs and GIDs according to some certain rules, and it also tries to map POSIX UIDs and GIDs back to Windows SIDs.

Generally, for a local, non-domain user, this mapping has nothing to do with the username and depends only on the last portion of the user’s SID.

It is worth noting that starting from version 5.3, JuiceFS.exe introduces a new mount option, admin-as-root, which is enabled by default (true). When this option is enabled, the built-in Windows Administrator user is automatically mapped to the Linux root user (UID=0). If your write operations are performed as Administrator, you have full control over the file system. If you want to disable this behavior, you can use the --admin-as-root=false option when mounting.

In addition, we also provide another mount option, --as-root. When this option is specified, all operations under the mount point are performed as the root user. At the same time, to handle permission compatibility on Windows, all files under the mount point will have their owners mapped to the Authenticated Users group (S-1-5-11) on Windows.

Troubleshooting Mount Failures

If you encounter issues mounting, please try the following:

• Use -f --debug --fuse-access-log D:\\fuse.log to mount in the foreground and collect detailed output and a FUSE access log.
• When mounting in the background, add --log <path> to send logs to a file.
• Run diag.bat in your WinFsp install folder (usually C:\Program Files (x86)\WinFsp\bin) to generate diagnostic information.
• Test the WinFsp service by running net use X: \\memfs64\share to mount a WinFsp memory file system to test if the WinFsp components work(requires the development components installed with WinFsp).
• If the problem persists, please include the logs above when you contact our support team.

Auto-Mount When System Starts

Currently, JuiceFS does not support automatic mounting on Windows. If you need the file system to be mounted automatically at system startup, consider using the Windows Task Scheduler or tools such as winsw to achieve this.

note

When JuiceFS performs a background mount by default, it relies on the system command net use. The net use command provides a /persistent option, which can be used to configure system-level automatic mounting. If you encounter issues related to this behavior, try adjusting this option and then perform the mount again.

Known Issues

Close-Open Consistency

Because WinFsp handles CloseHandle(IRP_CLEANUP) differently (it does not block like Linux FUSE), JuiceFS on the current WinFsp beta (2025) cannot guarantee close-open consistency as Linux can.

This issue has already been fixed in the latest WinFsp development branch. If you require consistency guarantees related to this issue, please contact us to obtain the WinFsp installer package we provide.

Overwrite by Non-Owner

WinFsp’s ACL translation omits WRITE_EA for POSIX "group" and "others" write permissions (its behavior follows Windows SFU). As a result, even if the permission mode of a file is 0666, non-owner users may not be able to overwrite it.

We are working on a fix.

Special File Attributes

Windows-only attributes such as read-only or hidden are not yet supported by JuiceFS.

Case Sensitivity

Windows filesystems are case-insensitive by default. Although JuiceFS stores names case-sensitively in its metadata, it ignores case on Windows. If you happen to have two files in the same directory whose names differ only by case (e.g. a.txt and A.TXT), you may see unexpected behavior.

The Windows kernel itself may also display newly created filenames in all-caps (e.g. creating a.txt becomes A.TXT). For performance reasons, JuiceFS does not return exact-case names in its directory listings by default. If you require exact-case filenames, use ```--report-case`` option when mounting.

“My Computer” Not Auto-Refreshing

Due to Windows’ mount-detection mechanism, "This PC" may not immediately show new mounts. You can manually refresh or simply cd to the drive letter to verify access.

Unsupported Features

• Creating symbolic links is not supported on Windows.