# msvc-wine: Running MSVC Build Tools on Linux Through Wine

> msvc-wine downloads Visual Studio compiler components, adds compatibility wrappers, and exposes x86, x64, arm, and arm64 tools to Unix build systems. It suits Linux and other Unix environments that need MSVC headers and libraries through Wine or Clang in MSVC mode.

**mstorsjo/msvc-wine** — Scripts for setting up and running MSVC in Wine on Linux

- Repository: https://github.com/mstorsjo/msvc-wine
- Stars: 1,393 · Forks: 127
- Language: Shell
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/mstorsjo-msvc-wine

## Why msvc-wine Exists for Unix MSVC Builds

msvc-wine addresses a distribution gap between Microsoft's Windows toolchain and Unix-based build systems. A project hosted on Linux may still need Windows object formats, MSVC headers, Windows SDK libraries, or compiler behavior that differs from GCC and Clang defaults. The repository provides a way to obtain those components and make them usable from Unix commands.

The README describes two related parts. A Python script downloads and unpacks MSVC and the Windows SDK. Installation scripts then wrap and adjust the unpacked files so MSVC can be invoked through Wine by Unix build tools. The same downloaded components can also serve tools such as `clang-cl`, which can run natively on Linux while targeting MSVC.

The intended audience is developers maintaining cross-platform builds, release automation, or CI systems that need a Windows compiler environment without installing native Visual Studio on the host. The prepared installation contains tool directories for `x86`, `x64`, `arm`, and `arm64`. The relevant directory must be placed before other compiler directories in `PATH`.

This is a compatibility arrangement, not a redistribution of Visual Studio. The README says downloading and installing the components requires accepting Microsoft's license. It also says Visual Studio and the installed toolchain are not redistributable. The repository's `LICENSE.txt` is a separate custom license whose details are not summarized in the README, so license review must cover both repository terms and Microsoft's terms before an installation is copied into an image or shared system.

## How msvc-wine Downloads, Wraps, and Exposes MSVC

The download stage is `vsdownload.py`. According to the README, it uses the same installer manifests as the Visual Studio 2017 and 2019 installer to download required Visual Studio components, then unpacks MSVC and the Windows SDK. Unpacking depends on recent versions of `msitools` and `libgcab`, with the README naming versions 0.98 and 1.2 as sufficient.

The installation stage is `install.sh`. The repository contains `wrappers`, `patches`, `fixinclude`, `lowercase`, and `msvctricks.cpp`, which indicates that installation does more than copy files. It prepares wrappers and makes compatibility adjustments to the unpacked Microsoft files. The README characterizes this work as making MSVC usable from Unix build tools with Wine.

After installation, the Wine-oriented tool wrappers are located below `<dest>/bin/<arch>`. The `PATH` entry selects both the architecture and the wrapper layer. A command such as `cl` is then available to CMake or another Unix build program, while Wine handles execution of the Windows executable.

The native compiler path is separate. `msvcenv-native.sh` sets environment values used by Clang and LLD. The README says `INCLUDE` and `LIB` are configured from the installation, while `BIN` identifies the relevant architecture directory. This path avoids running the compiler through Wine, but it still needs the MSVC and Windows SDK headers and libraries.

The design therefore produces two distinct interfaces from one toolchain preparation: Wine wrappers for actual MSVC execution and environment variables for native Unix compilers. The choice affects dependencies, failure modes, and version compatibility.

## Installing msvc-wine and Configuring a CMake Build

The README's Ubuntu example installs Wine, Python, unpacking dependencies, certificates, and `winbind`. Run the package installation command before downloading the toolchain. `winbind` is relevant to CMake builds because MSVC can use a separate PDB server during compiler probing.

```bash
apt-get update
apt-get install -y wine64 python3 msitools ca-certificates winbind
```

The documented destination is `~/my_msvc/opt/msvc`, which avoids requiring root privileges. Run the downloader first, then the installer. The README presents this sequence as the normal local installation path.

```bash
./vsdownload.py --dest ~/my_msvc/opt/msvc
./install.sh ~/my_msvc/opt/msvc
```

The README also gives optional Wine startup commands. They stop a possible old server, start a persistent server, and run an initial Wine process so background services are initialized before compilation.

```bash
wineserver -k
wineserver -p
wine64 wineboot
```

CMake must find the wrapper before other compilers. The example selects `x64`, sets `CC=cl` and `CXX=cl`, and marks the build as targeting Windows.

```bash
export PATH=~/my_msvc/opt/msvc/bin/x64:$PATH
CC=cl CXX=cl cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_SYSTEM_NAME=Windows
make
```

The README states that CMake 3.23 is required. It also explains that CMake can invoke the compiler in `Debug` mode during its initial tests even when `-DCMAKE_BUILD_TYPE=Release` is selected. If that probe uses `/Zi` and `/FS`, MSVC starts `mspdbsrv.exe`, which needs `winbind` for communication. For CMake 3.25 or newer, the documented embedded-debug-information configuration can avoid that dependency during probing.

## Using msvcenv-native.sh with Clang and LLD

The native Clang path does not execute MSVC through Wine. It still requires the MSVC and Windows SDK headers and libraries, so the downloader and installer remain part of setup. For this path, the README lists fewer prerequisites because Wine is not needed.

```bash
apt-get update
apt-get install -y python3 msitools ca-certificates
./vsdownload.py --dest ~/my_msvc
./install.sh ~/my_msvc
```

Set `BIN` to the directory for the target architecture and source the generated environment script. Sourcing the script is important because the variables must remain in the current shell used by the compiler commands.

```bash
BIN=~/my_msvc/bin/x64 . ./msvcenv-native.sh
```

With that environment active, the README says `clang-cl` can compile a source file and `lld-link` can create an executable without explicit paths to the MSVC installation.

```bash
clang-cl -c hello.c
lld-link hello.obj -out:hello.exe
```

The direct Clang form can select the Windows MSVC target and LLD as the linker.

```bash
clang --target=x86_64-windows-msvc hello.c -fuse-ld=lld -o hello.exe
```

Linux distributions do not always provide commands with those exact names. The README says missing `clang-cl` or `lld-link` commands can be represented by symlinks to compatible `clang` and `lld` binaries because those binaries change behavior according to the name used to invoke them. The documentation does not claim that every distribution build contains every target or linker feature.

Version selection is a documented constraint. The README says older Clang and LLD versions may not work with libraries from the newest MSVC and Windows SDK. It states that at least Clang/LLD 13 is required for MSVC 2019 16.8 or newer.

## Dockerfile.clang and the Native Windows Alternative

The repository includes a reproducible `Dockerfile` based on `ubuntu:24.04`. It installs `wine64`, `python3`, `msitools`, and `ca-certificates`, copies the downloader, installer, helper files, and wrappers, then installs MSVC under `/opt/msvc`. It removes installation-only files and keeps `msvcenv-native.sh` at `/opt/msvc`. The image provides a contained way to prepare the toolchain without placing it in the host user's home directory.

The Dockerfile also initializes Wine and waits for `wineserver` to exit before continuing. That sequence is relevant to Wine prefix stability. The file comments describe starting a persistent Wine server as an optional later-stage action for containers that actually use MSVC.

The main alternative is native Windows Visual Studio. On Windows, the README says to download with `vsdownload.py` and then run one of the generated `vcvars` batch files from Windows CMD. For example, a command prompt can load the x64 environment with `vcvars64.bat`. That route uses native Windows tools and Windows batch environment setup rather than Unix shell wrappers.

Another alternative is Clang and LLD running directly on Linux in MSVC mode. This avoids Wine execution, but it still depends on the downloaded MSVC and Windows SDK files and requires compatible compiler and linker versions. The practical choice is therefore based on execution environment and support requirements. Use msvc-wine wrappers when the goal is to run MSVC tools through Wine. Use the native environment when avoiding Wine is more important and the selected Clang/LLD version is compatible.

## Maintenance, Upgrade Scope, and License Consequences

The repository is not archived, and its last push was on 2026-05-24. The repository has no GitHub releases. The README does not define a release cadence, upgrade command, or migration procedure. Maintenance therefore depends on changes to `vsdownload.py`, `install.sh`, wrappers, patches, Visual Studio component manifests, and the behavior of current MSVC and Windows SDK files.

Several dependencies have separate roles. `msitools` and `libgcab` affect unpacking. Wine affects wrapper execution. `winbind` affects PDB server communication during some CMake probes. Clang and LLD versions affect native MSVC-mode compilation. The stated requirement for Clang/LLD 13 with MSVC 2019 16.8 or newer shows why changing the downloaded compiler components can affect an otherwise unchanged Unix project.

The README explicitly states that Visual Studio is not redistributable and that the installed toolchain is not redistributable. The repository's custom `LICENSE.txt` is separate from Microsoft's license for the downloaded components. A user preparing a local installation must review the actual terms for downloading, acceptance, CI use, container storage, and distribution. The presence of a repository license does not itself grant redistribution rights for Microsoft's files.

Before upgrading, identify whether the build invokes `cl` through Wine or uses `clang-cl` and `lld-link` directly. Then verify the selected architecture, the generated environment paths, and the compiler version against the downloaded MSVC and Windows SDK release.

## Conclusion

msvc-wine is appropriate for projects that compile Windows binaries with MSVC from Linux or another Unix system, including CMake builds that invoke `cl` through Wine. It is less suitable for developers who need a fully supported native Visual Studio installation, cannot accept Microsoft's license terms, or cannot maintain the Python, msitools, libgcab, Wine, and toolchain compatibility dependencies. Before adoption, verify that your Clang or LLD version is compatible with the selected MSVC and Windows SDK components, then inspect the generated `msvcenv-native.sh` environment against the target architecture. The project is not archived and its last push was on 2026-05-24, but it has no GitHub releases, so upgrades require checking repository scripts and component compatibility directly.

## FAQ

### How do I install msvc-wine on Linux?

Install `wine64`, `python3`, `msitools`, `ca-certificates`, and `winbind`, then run `./vsdownload.py --dest <dir>` followed by `./install.sh <dir>`. The README identifies `msitools` 0.98 and `libgcab` 1.2 as sufficient unpacking versions.

### Can msvc-wine be used without Wine?

Yes. The downloader can unpack MSVC and Windows SDK components without the Wine wrapper layer, after which `msvcenv-native.sh` configures `INCLUDE`, `LIB`, and `BIN` for Clang and LLD in MSVC mode.

### Does msvc-wine work with CMake?

The README says CMake 3.23 or newer is required. For CMake 3.25 or newer, `CMP0141` and `-DCMAKE_MSVC_DEBUG_INFORMATION_FORMAT=Embedded` can avoid the `winbind` requirement during compiler probing.

### Which Clang and LLD versions are supported?

The README says older versions may fail with the newest MSVC and Windows SDK libraries, and states that at least Clang/LLD 13 is required for MSVC 2019 16.8 or newer. Some distributions may expose version-suffixed names such as `clang-cl-14`.

## Sources

- [Issues](https://github.com/mstorsjo/msvc-wine/issues)
- [mstorsjo/msvc-wine on GitHub](https://github.com/mstorsjo/msvc-wine)
- [README](https://github.com/mstorsjo/msvc-wine/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mstorsjo-msvc-wine