{"id":28590031,"url":"https://github.com/lenml/lets-build-wsl2-kernels","last_synced_at":"2025-06-11T08:13:22.054Z","repository":{"id":285893030,"uuid":"959683455","full_name":"lenML/lets-build-wsl2-kernels","owner":"lenML","description":"This repository automates building custom WSL2 kernels using GitHub Actions.","archived":false,"fork":false,"pushed_at":"2025-04-03T08:29:13.000Z","size":8,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-03T08:29:29.686Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lenML.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-04-03T07:24:13.000Z","updated_at":"2025-04-03T08:29:17.000Z","dependencies_parsed_at":"2025-04-03T08:40:02.803Z","dependency_job_id":null,"html_url":"https://github.com/lenML/lets-build-wsl2-kernels","commit_stats":null,"previous_names":["lenml/lets-build-wsl2-kernels"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lenML%2Flets-build-wsl2-kernels","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lenML%2Flets-build-wsl2-kernels/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lenML%2Flets-build-wsl2-kernels/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lenML%2Flets-build-wsl2-kernels/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lenML","download_url":"https://codeload.github.com/lenML/lets-build-wsl2-kernels/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lenML%2Flets-build-wsl2-kernels/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259227962,"owners_count":22824907,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-11T08:12:32.066Z","updated_at":"2025-06-11T08:13:22.018Z","avatar_url":"https://github.com/lenML.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# lets-build-wsl2-kernels 🛠️\n\n[![GitHub Actions](https://img.shields.io/github/actions/workflow/status/lenML/lets-build-wsl2-kernels/build-kernel.yml?style=flat-square)](https://github.com/lenML/lets-build-wsl2-kernels/actions)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)\n\nThis repository provides automated builds of Microsoft's official WSL2 kernel sources, compiling and releasing only the bzImage kernel files.\n\n## Features ✨\n\n- Automates building official Microsoft kernel sources exactly as released\n- Provides access to historical kernel versions\n- Only distributes the compiled bzImage (kernel binary)\n- Does NOT provide or modify any vhdx files\n\n## Download Pre-built Kernels\n\nhttps://github.com/lenML/lets-build-wsl2-kernels/releases\n\n## Usage 🚀\n\n### Manual Build via GitHub UI\n\n1. Go to \"Actions\" tab\n2. Select \"Build WSL2 Kernel\"\n3. Click \"Run workflow\"\n4. Specify kernel version (e.g. `5.15.90.1`)\n5. Click \"Run workflow\"\n\n### Install Compiled Kernel\n\n1. Download the bzImage artifact after build completes\n2. Place it in your preferred location (e.g. `C:\\Windows\\System32\\lxss\\tools`)\n3. Create/modify `%USERPROFILE%\\.wslconfig`:\n\n```ini\n[wsl2]\nkernel=C:\\\\path\\\\to\\\\bzImage\n```\n\n4. Restart WSL: `wsl --shutdown`\n\n### Local Build\n\nTo build locally from official sources:\n\n```bash\n./scripts/build.sh [version]\n```\n\nExample:\n```bash\n./scripts/build.sh 5.15.90.1\n```\n\n## Why This Exists ❓\n\nMicrosoft maintains the [WSL2-Linux-Kernel](https://github.com/microsoft/WSL2-Linux-Kernel) but:\n- Doesn't provide pre-built historical kernel versions\n- Only distributes kernels through Windows Update\n- Makes it difficult to test different kernel versions\n\nI encountered issues while fine-tuning models using **Unsloth**, and I suspect they are related to the WSL2 kernel. To experiment with different WSL kernels, I created this repository.\n\nThe specific Unsloth issue can be found here: https://github.com/unslothai/unsloth/issues/1744  \nProblems I discovered include:\n\n- Some WSL kernel versions have serious memory management issues:\n  - Memory is requested but cannot be released, even when `pageReporting=true` is enabled.\n  - `memlock` limits vary—some WSL instances have a higher or even unlimited locked memory cap, but typically the limit is around 2GB. In my tests, it sometimes allows only 2GB, which is entirely dependent on the WSL kernel.\n    - `memlock` has a hard limit that seems unchangeable within WSL.\n    - `memlock` appears to overestimate current locked memory; repeated locking of the same memory can be counted multiple times (as documented in [WSL's infiniband/user_verbs.rst](https://github.com/microsoft/WSL2-Linux-Kernel/blob/main/Documentation/infiniband/user_verbs.rst#memory-pinning)).\n- Some WSL kernels are incompatible with Docker Desktop.\n\n## Memory Management in WSL Kernels\n\nThe WSL2 kernel has specific behaviors around memory allocation and locking:\n\n1. **Performance Monitoring Memory**: \n   - The `perf_event_mlock_kb` setting governs memory available for performance monitoring\n   - This extends the `RLIMIT_MEMLOCK` limit but only for perf_event mmap buffers\n   - Processes with `CAP_IPC_LOCK` capability bypass these limits\n   - [See documentation](https://github.com/microsoft/WSL2-Linux-Kernel/blob/main/Documentation/admin-guide/perf-security.rst#memory-allocation)\n\n2. **Memory Pinning**:\n   - Direct I/O requires memory regions to stay at fixed physical addresses\n   - The kernel accounts pinned memory in `pinned_vm`\n   - Pages pinned multiple times are counted each time (may overestimate actual usage)\n   - [Documentation reference](https://github.com/microsoft/WSL2-Linux-Kernel/blob/main/Documentation/infiniband/user_verbs.rst#memory-pinning)\n\nThese behaviors explain some of the memory management challenges encountered when running memory-intensive workloads in WSL2.\n\n## License 📄\n\nKernel code is under Microsoft's original licenses. Build scripts are MIT licensed.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flenml%2Flets-build-wsl2-kernels","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flenml%2Flets-build-wsl2-kernels","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flenml%2Flets-build-wsl2-kernels/lists"}