In the recently released JuiceFS Community Edition 1.3 and Enterprise Edition 5.2, we’ve significantly optimized Windows platform support. Early JuiceFS versions attempted to support the Windows platform, but they suffered from usability and stability issues. This prevented them from reaching a reliably functional state.
Last year, we decided to comprehensively enhance the Windows platform support, aiming to improve performance while delivering a more stable and high-quality user experience. In a recent cloud rendering scenario test, we conducted small-file read/write performance tests on 3,000 Windows clients. The results demonstrated that performance now meets the demands of large-scale usage. We’ll share the detailed findings of this test in a follow-up blog post.
Throughout this year-long optimization initiative, we encountered significant challenges due to the scarcity of comprehensive documentation and reference materials for Windows platform development. This article will provide a detailed exposition of the critical issues we confronted, the corresponding solutions we implemented, and the progress we achieved.
It's important to note that the current release remains in beta phase—while critical functionalities are fully operational, ongoing testing and user feedback are essential for further refinement.
We encourage users with relevant needs to deploy this version and contribute their insights through our community channels. Our team remains committed to providing responsive support and addressing all reported issues.
Our goals
For the Windows version, the core task was porting the existing file system logic to the Windows platform. There were two primary approaches:
- Mounting via Linux and initiating Samba services to share files with Windows. This method may introduce additional protocol overhead and configuration complexity, increasing operational costs.
- Running the client natively on Windows, delivering a more authentic Windows experience. While previous versions contained numerous bugs, our current beta version focuses on optimizing this approach.
We aimed to deliver a truly production-ready version that:
- Ensures compatibility with most Windows applications when running on JuiceFS
- Supports data read/write and file management features
- Meets stringent performance benchmarks
Therefore, in this release, our development tasks include:
- Toolset restoration: The CLI toolkit is fundamental to JuiceFS operations, but common commands previously malfunctioned on Windows. Below, we’ll describe the optimizations and improvements made to each of the major commands.
- User experience optimization: Previous versions exhibited significant user experience challenges, particularly in performance and operational complexity. We're now prioritizing optimizations in these areas to deliver smoother and more simple workflows.
- Bug fixes:
- Authentication and permission management issues
- Windows API-related bugs, specifically addressing error code returns and logical inconsistencies Various minor bugs
Implementation approach
In this optimization effort, we leveraged a critical component—WinFsp (Windows File System Proxy), an open-source library that provides two essential features:
- An efficient file system driver interface: Implements a Windows File System Driver (FSD).
- FUSE (Filesystem in Userspace) compatibility: Offers a high-level FUSE interface. FUSE provides two APIs—high-level and low-level. JuiceFS uses the low-level interface, but with path translation, we successfully integrated it with the FUSE layer.
Data flow with WinFsp integration
After integrating WinFsp, the Windows read operation follows this workflow (refer to the figure below):
- Upper section: User-space processes
- Lower section: Kernel-space operations
The figure shows the data flow path from the application to the driver:
- In user space, when an application performs I/O operations (such as reading or writing files), the data is transferred to kernel space and then to the Windows I/O Manager, a core component in the Windows kernel. This component manages all I/O operations.
- The Windows I/O Manager converts these I/O operations into Windows I/O request packages (IRPs) and forwards them to the file system driver layer. This simplifies some of the layers, but ultimately these requests are passed to the file system driver layer, specifically the WinFsp file system driver.
- When the file system driver receives a request, it forwards it to the WinFsp DLL. This DLL is responsible for interfacing with the Windows kernel data.
- In our JuiceFS implementation, applications link against the WinFsp DLL to handle I/O requests. When Windows I/O requests are passed to the DLL, WinFsp converts them into FUSE interfaces and handles callbacks through the Windows FUSE compatibility layer. The majority of work is on this layer, including bug fixes and performance optimizations.
- After processing these operations, the final request is handed to the JuiceFS core VFS (virtual file system) layer, which is responsible for implementing specific file system logic and request processing.
Remaining challenges
We still face four challenges in adapting JuiceFS to Windows:
Unix-Windows divergence
While WinFsp helps us convert I/O requests to the FUSE interface, we still need to address fundamental differences between Unix and Windows:
- Permission management differences: For example, Linux file permissions (such as read, write, and execute) and extended permissions (such as ACLs) are completely different from the Windows permissions model. Windows uses discretionary access control lists (DACLs) to define permissions and supports permission inheritance, which is significantly different from the Unix permissions model. Therefore, while WinFsp handles some permission conversion, we still need to figure out how to effectively map these two permission systems to better support Windows applications.
- Differences in system characteristics: Unix and Windows also have many fundamental differences in file system characteristics. These include hard links, soft links, mount methods, directory lengths, character limits, and file attributes. Our JuiceFS core file system is based on the Unix file system design, so we need to address or work around these differences to ensure proper operation on Windows platforms.
- API differences: Unix and Windows have many differences in system APIs. Although we use the Go language to simplify handling some of these API differences, some situations still require manual workarounds. For example, there's no direct solution on Windows for obtaining information like UIDs and GIDs. While Go has made many cross-platform optimizations, some specific system APIs still require us to handle these differences manually to ensure system compatibility and stability.
Differences between Linux FUSE and WinFsp FUSE
Previously, JuiceFS has been interfacing with the low-level FUSE interface, while WinFsp FUSE is a high-level FUSE interface. There are fundamental differences between the two:
- Low-level FUSE typically uses inodes as callback parameters, while high-level FUSE primarily uses paths as callback parameters. This is an obvious difference between the two.
- Although WinFsp provides a high-level FUSE callback interface, its implementation logic doesn't fully conform to the Linux libfuse implementation. Therefore, when using WinFsp FUSE, we often encounter situations where certain behaviors appear natural and consistent in Linux, exactly as described in the FUSE documentation, but the callback logic for these behaviors differs in WinFsp. This requires careful attention and resolution of these platform behavioral differences.
Opaque Windows kernel
During the development process, we also had to deal with the opaque Windows kernel. Because the Windows kernel is not open source and its documentation is limited, debugging and observing its behavior is difficult. This makes the entire development process full of uncertainty. For developers, the operational mechanisms of the Windows kernel are like a closed black box, requiring continuous experimentation and reverse engineering to understand and adapt.
Limited FSD documentation resources
FSD documentation resources are limited. Microsoft does not publicly release complete documentation for Windows kernel development. Many APIs are compiled by third parties, and official documentation is scarce. In fact, the only book dedicated to Windows file system drivers is Windows NT File System Internals: A Developer's Guide, published in 1997. Despite numerous errors (mostly due to inapplicability to current versions), Windows file system driver developers still rely solely on this book as a reference. These limited documentation resources require us to invest more time and effort in collecting and studying information when troubleshooting problems and understanding Windows file system behavior.
Achievements
In this section, we'll share the specific improvements we made in the beta release. They can be divided into two areas: JuiceFS-related enhancements and WinFsp-related optimizations.
JuiceFS improvements
Toolset
The toolset is crucial for daily JuiceFS use. After deployment, users rely on the toolset for performance testing, monitoring, and other operations. For example, basic performance testing typically involves running the bench command. However, in earlier versions, this command failed to run on Windows, with the system prompting that the command was not supported on Windows.
Furthermore, after mounting the file system, we often need to monitor key performance metrics, such as raw data latency, throughput, object storage performance, and distributed cache throughput. However, in earlier versions, these monitoring features also failed to function properly. The system prompted that the .control file could not be opened.
These issues have been fixed in JuiceFS Community Edition 1.3 and Enterprise Edition 5.2. The toolset has now evolved from being almost completely unusable to being essentially usable.
API compatibility
In earlier versions, some users may have encountered API compatibility issues, particularly when using JuiceFS as a Git directory. Some users found that Git commands did not work properly when executed directly. This issue was primarily due to incompatible error code handling with Windows. We did not handle certain error codes the way Windows itself does, resulting in applications that rely on them not working properly. This section primarily involves improvements to API compatibility.
In addition, in earlier versions, mount status anomalies could occur. For example, after the mount process completed, the system might report a mount failure even though the file system was actually mounted, or the mount success notification might display incorrectly. In the current beta version, we’ve fixed and optimized these behaviors, including Git command errors.
Achieving 100% consistency in error codes between Linux and Windows is extremely challenging due to their inherent differences. However, through continuous feedback and improvements, we are constantly refining these compatibility issues to deliver a more stable Windows version.
User/Permissions
In earlier versions, our permission management had some ambiguities. For example, when User A set certain permissions or configured access in specific areas, there was no clear expectation or unified handling mechanism. This led to issues such as User A mounting the file system but lacking a defined method to allow colleagues to access the files. To enable file sharing, we previously used a parameter called as-root, which elevated all user permissions to root-level access. While this temporarily resolved the issue, it was not an ideal solution.
In the current beta version, we’ve optimized permission management. By redesigning the permission mechanism to clarify its objectives, we ensure compatibility with Windows API operations while aligning as closely as possible with POSIX behavior. Specifically, when UID mapping is disabled, we ensure that Linux user UIDs (such as 1001) are correctly mapped and shared in Windows, guaranteeing that users with the same UID are treated uniformly across systems.
In addition, if UID mapping is enabled, the scenario becomes more complex, but we’ll also provide support for it. Ultimately, our goal is to make Windows permission management as consistent with POSIX behavior as possible, delivering clearer and more reliable access control for users.
Mounting
In earlier versions, mounting operations could only be performed in the foreground, lacking support for background mounting. This created a significant limitation: if users wanted to mount a file system in the background for sharing with others, they had to rely on third-party tools or manual configurations. For example, they might need to use Microsoft's built-in command-line tools to create a system service or manually write YAML configuration files—a process that was both cumbersome and error-prone.
In JuiceFS Community Edition 1.3 and Enterprise Edition 5.2, we’ve resolved this issue by introducing native background mounting support. Aligning with the Linux version, users can now enable background mounting in the Community Edition using the -d parameter, while the Enterprise Edition supports background mounting by default. For foreground mounting, the -f parameter is available.
In addition, previous Community Editions did not allow mounting the same file system to multiple drive letters. Now, in the Enterprise Edition, we’ve implemented this functionality, enabling users to mount a single file system across multiple drive letters. Currently, this feature is exclusive to the Enterprise Edition.
Performance
In earlier versions, there existed a widespread and severe issue where small file read/write performance was extremely poor, and file attribute retrieval efficiency was low.
In JuiceFS Community Edition 1.3 and Enterprise Edition 5.2, we implemented significant optimizations that dramatically improved small files’ read/write performance. These performance enhancements can be verified and benchmarked using the bench tool, which provides read/write performance metrics for both large and small files.
For example, when tested on an Alibaba Cloud instance with 88 cores and 16 GB memory, using Alibaba Cloud Redis and self-built MinIO under default command-line parameters, we observed:
- Small file write performance remained comparable to version 1.2.
- Small file read performance showed remarkable improvement, increasing from 200 small files per second in v1.2 to nearly 1,000 small files per second in v1.3.
Furthermore, file attribute retrieval performance was substantially optimized. Previously only about 200 attributes could be fetched per second. However, this version achieves up to 4,500 operations per second. While these results may vary due to caching effects, the overall optimization results are exceptionally significant.
Another critical optimization addresses the impact of path depth. In version 1.2, performance would degrade dramatically as file path depth increased. For example, with three-level directory structures, small file read performance could drop to just dozens of files per second. In version 1.3, however, performance remains stable even with three-level deep paths, showing no significant degradation. This improvement ensures users won't experience performance decrease when creating deeper directory structures.
Additional optimizations and fixes
Subdirectory mounting and file rename operations, which previously might fail to execute properly, have been optimized and fixed. Earlier versions frequently encountered unexplained errors during rename operations that prevented successful completion. These issues have now been resolved. Furthermore, while not listed here, other potential factors are still under continuous improvement.
FSD issue fixes and troubleshooting
POSIX file permission mapping
In previous versions, we encountered an issue with file permission mapping, particularly with the 0666 permission setting. According to the POSIX standard, 0666 grants all users read and write access to a file. However, on Windows, even when this permission was set, the Everyone group (that is, all users) still couldn't perform overwrite operations.
The root cause lies in WinFsp's incomplete handling of these permission mappings. Even when similar permissions were configured on Windows, the system didn't fully replicate POSIX behavior, preventing universal read/write access as expected.
Currently, this issue still exists in WinFsp's implementation. We’ve submitted a pull request to the upstream project to address this, aiming to align Windows' behavior with POSIX standards and ensure proper file permission handling on the Windows platform.
Close-to-open consistency
By default, JuiceFS adheres to the close-to-open consistency model. This means that after a file is closed, the user will be able to see previously written data the next time the file is opened, even on a different node.
However, WinFsp and Windows handle file closure differently. WinFsp's default behavior doesn't asynchronously wait for the FUSE application to complete data processing when a file is closed. Specifically, when an application calls CloseHandle to close a file handle, Windows applications via WinFsp return immediately—without blocking—even if local data hasn't been fully uploaded to the cloud. This behavior breaks close-to-open consistency, potentially causing users to read incorrect file length information upon reopening.
To address this issue, we’ve made corresponding adjustments to the WinFsp source code to ensure close-to-open consistency can be maintained on the Windows platform, guaranteeing unaffected data synchronization and consistency.
Kernel cache manager utilization
In WinFsp's processing workflow, it did not use the kernel cache manager by default. This led to low file read performance. The cache manager is typically responsible for caching and readahead operations, significantly enhancing file system read efficiency. However, under WinFsp's default configuration, the cache manager was not effectively utilized, thereby affecting system performance.
To resolve this issue, we identified and fixed it at the FSD level and investigated how to correctly enable Cache Manager in WinFsp. Our goal is to significantly improve file read performance and optimize overall system performance by correctly enabling and configuring cache management.
JuiceFS Windows client optimization summary:
| Feature | Community Edition 1.2 | Community Edition 1.3 / Enterprise Edition 5.2 |
|---|---|---|
| Tool set | Mostly unavailable | Mostly available |
| API compatibility | Incorrect error codes | Optimized and corrected |
| Identity issues | Chaotic and mishandled | Standardized and fixed |
| Mounting | No background mountingNo multi-drive-letter mounting | Enterprise Edition supports multi-drive-letterBackground mounting supported |
| Performance | Poor small file and metadata performance | Significantly optimized |
| Other bugs | Subdirectory mounting failuresRename failuresClose-open consistency issues | Fixed/Fixing |
Future plans
In the future, we’ll continue to focus on the usability of the Windows client, including bug fixes, feature expansion, and support for symlinks. We’ll also work hard on performance improvements. With increasingly complex usage scenarios, growing data volumes, and a wide range of technical aspects involved, optimizing the Windows platform support will be a long-term process.
Many users have expressed interest in active directory (AD) domain account integration. In Windows environments, AD domain binding would be a highly practical feature, and we’re actively researching this requirement. If you have any questions for this article, feel free to join JuiceFS discussions on GitHub and community on Slack.
