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 the foreground mount, the file system will only be visible to the user who ran the mount command (e.g. Administrator). Other users will not see the drive.

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 uses ACLs (Access Control Lists).
• Linux uses the POSIX permission model.

JuiceFS stores metadata in POSIX format, so some behaviors may differ on Windows. For example, when Windows creates a new file, its permissions are determined by the parent directory’s security descriptor. If you want new files to have a consistent umask, add -o "create_umask=xxx" to your mount options (e.g. xxx=022 gives files 644).

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’s worth noting that on Windows, JuiceFS does not map the SYSTEM or Administrator accounts to Linux’s root (UID 0). If you need root-equivalent behavior on Windows, you can mount with the --as-root option.

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

JuiceFS on Windows does not yet support automatic mounting. If you need a mount at startup, consider using Windows Task Scheduler or a similar tool to run the mount command at boot.

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.

We are working on a fix.

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.