From 57ed761647ae14d04f7f3b36725943310bb3eb3e Mon Sep 17 00:00:00 2001
From: Octopus <liyuan851277048@icloud.com>
Date: Fri, 3 Apr 2026 13:58:29 +0800
Subject: [PATCH] docs: add WSL uv sync memory allocation troubleshooting
 (fixes #101)

WSL2 default memory limits can cause uv sync to fail with a memory
allocation error when building packages like transformers or pillow.
Add a FAQ entry documenting two workarounds: increasing the WSL2 memory
cap via .wslconfig, and limiting parallel builds with UV_CONCURRENT_BUILDS.
---
 README.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/README.md b/README.md
index 64d4deb6..9e16f409 100644
--- a/README.md
+++ b/README.md
@@ -890,6 +890,21 @@ bash scripts/collect_trace_qwen3.sh
 1. **Review logs**: Check `logs/` directory for detailed error messages
 1. **Verify data path**: Ensure benchmark data is downloaded and in correct location
 
+#### **Q: `uv sync` fails with memory allocation error on WSL**
+
+**A:** WSL2 imposes a memory cap that can cause `uv sync` to fail when building heavy packages (e.g. `transformers`, `pillow`). Two options:
+
+1. **Increase WSL2 memory limit** (recommended): Create or edit `%UserProfile%\.wslconfig` on your Windows host, then restart WSL (`wsl --shutdown`):
+   ```ini
+   [wsl2]
+   memory=8GB
+   ```
+
+2. **Limit parallel package builds** (no restart required): Set the `UV_CONCURRENT_BUILDS` environment variable before running `uv sync`:
+   ```bash
+   UV_CONCURRENT_BUILDS=1 uv sync
+   ```
+
 #### **Q: Out of memory errors**
 
 **A:** Solutions: