WSL Installation Report - Detailed Findings

I successfully installed and tested LEANN on Windows 11 via WSL2 (Ubuntu). Here are my detailed findings that might help others and inform future Windows/WSL support decisions.

Environment

Host: Windows 11 with WSL2 (Ubuntu)
Python: 3.12.3 (via system package)
Package Manager: uv
Network: Corporate environment with Fortinet VPN/Firewall

Installation Success ✅

Installation works via WSL:

# Create venv and install
uv venv .venv-wsl
source .venv-wsl/bin/activate
uv pip install leann
# Successfully installed 140 packages

Note for corporate networks: WSL2 with NAT networking may have HTTPS connectivity issues due to VPN/firewall. Workaround: Run an HTTP proxy on Windows (e.g., pip install proxy.py && proxy --hostname 0.0.0.0 --port 8888) and configure WSL:

export http_proxy=http://<windows-ip>:8888
export https_proxy=http://<windows-ip>:8888

What Works ✅

leann build - Index creation works perfectly (tested with PDFs, TXT, MD files)
leann search - Returns correct results via fallback mechanism
Python API - LEANNRetriever works with fallback

Critical Issue: ZMQ Embedding Server Fails ❌

The ZMQ embedding server consistently fails with:

[HNSW RNG] get_vector_zmq id=1751 cache_hit=0
WARNING - leann.embedding_server_manager - Server process did not terminate within 5 seconds, force killing...
⚠️ Embedding server failed: Failed to compute embeddings via server: Resource temporarily unavailable
⏭️ Falling back to direct model loading...

While the fallback works, it has severe performance implications.

Performance Comparison

Metric	WSL (with fallback)	Expected (native Linux)
Search latency	7m 38s	~1-2 seconds
Model loading	Every query	Once (cached)
ZMQ server	❌ Fails	✅ Works

The ~7.5 minute search time makes WSL unusable for practical applications. The time breakdown:

real 7m38.299s (wall clock)
user 0m47.258s (CPU user)
sys 0m18.869s (CPU system)

Most time is spent on network I/O (model download) and repeated model initialization.

Root Cause Analysis

The ZMQ issue in WSL appears to be related to:

Inter-process communication limitations in WSL2
Possible socket/IPC differences between native Linux and WSL
The embedding server subprocess not properly initializing

Suggestions

Documentation: Add a note that WSL works but with significant performance limitations
Server-mode option: Consider a persistent embedding server mode that can be started once and reused across queries
Model caching: Implement local model caching to avoid repeated downloads
Windows native: For true Windows support, the Rust HNSW backend would need Windows wheels

Conclusion

WSL installation is viable for development/testing only, not for production use. Users needing real performance should use native Linux or a Linux VM/container.

Happy to provide more details or help test potential fixes!

[TODO] Add support for Windows [Many requests] #14

Description

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions