lima-vm / lima-vm/lima

WSL2: improve support for generic templates and standard Lima configuration fields

Open
#5,152 6 comments 0 reactions 0 assignees View on GitHub
documentation expert host/Windows
Dominant language
Go
Stars
21.9k
Forks
957
Avg merge
2d 6h
Merged PRs (30d)
53

Description

## Current limitations

### Rootfs format restrictions

The WSL2 driver imports guests via:

```text
wsl.exe --import
```

which only accepts filesystem archives (`.tar`/`.tar.gz`).

As a result, templates referencing standard `.qcow2` or `.raw` cloud images cannot be used with the WSL2 backend.

Currently it is unclear whether this limitation should be:

* explicitly validated and documented, or
* abstracted by adding conversion/import helpers.

### Configuration fields ignored by the backend

`validateConfig()` currently warns and ignores several standard Lima configuration fields, including:

* `mounts`
* `networks`

This makes WSL2 behave differently from other drivers and limits template portability.

## Proposed direction

### Phase 1: Improve validation and documentation

* Explicitly validate supported image formats for `vmType: wsl2`.
* Provide clear error messages when unsupported image types (`qcow2`, `raw`, etc.) are used.
* Document how users can build or provide WSL-compatible rootfs archives.

### Phase 2: Support standard Lima mount semantics

Investigate mapping Lima `mounts:` entries onto WSL's existing host filesystem integration.

Possible approaches:

* translate Windows host paths into their `/mnt//...` equivalents;
* create symlinks or bind mounts inside the guest to honor `mountPoint`;
* generate appropriate `/etc/wsl.conf` entries during initialization.

### Phase 3: Reduce backend-specific special casing

Where feasible, allow WSL2 instances to consume a broader set of Lima templates without requiring a dedicated experimental template.

## Open questions

1. Should WSL2 reject unsupported image formats at validation time?
2. What level of `mounts:` compatibility is desirable for WSL2?
3. Is full template portability across drivers a goal for the backend?

I'd be interested in working on this if the direction aligns with the maintainers' vision for WSL2.

Contributor guide

Open the contributing guide

Research direction

Start at the WSL2 driver's validateConfig() and trace the wsl.exe --import path to understand current image-format validation and ignored fields. Compare the backend behavior with standard Lima template semantics, then clarify the maintainers' preferred scope for validation, documentation, and mounts before defining completion criteria.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
infrastructure, operating-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.