cargo-wix: A cargo subcommand to create Windows installers

A subcommand for Cargo that builds a Windows installer (MSI) using the WiX
Toolset from the build of a Rust binary project. It also supports signing the
Windows installer if a code signing certificate is available using the
SignTool application available in the Windows SDK.

Quick Start

Start a command prompt (cmd.exe) and then execute the following commands:

dosCopy
C:\>cargo install cargo-wix
C:\>cd Path\To\Project
C:\Path\To\Project\>cargo wix init
C:\Path\To\Project\>cargo wix

The Windows installer (MSI) for the project will be in the
C:\Path\To\Project\target\wix folder. Please see the Documentation for more
advanced usage, configuration, and customization.

Installation

The cargo-wix project can be installed on any platform supported by the Rust
programming language, but the WiX Toolset is Windows only; thus, this project is
only useful when installed on a Windows machine. Ensure the following
dependencies are installed before proceeding.

[!NOTE]
Cargo is installed automatically when installing the Rust programming language.
The stable-x86_64-pc-windows-msvc toolchain is recommended.

• Cargo
• Rust v1.88.0 or newer
• WiX Toolset v3.14.1 or newer
• Windows SDK (Optional), needed for signing the installer

[!IMPORTANT]
The WiX Toolset is available in two different variants: Legacy (v3.14.1) and
Modern (v4+). The Legacy variant uses a two-stage approach with a compiler,
candle.exe, and a linker, light.exe. The Modern variant uses a single stage
approach with a single executable, wix.exe, and a new XML schema and
namespace. The Legacy variant is no longer supported by the WiX Toolset
developers, FireGiant. Both variants are supported by the cargo-wix project
and the cargo wix subcommand, but usage of the Legacy variant is currently the
default.

[!WARNING]
As of April 3rd, 2026, the windows-latest GitHub Action image still only
contains the Legacy variant, v3.14.1, of the WiX Toolset. If the Modern variant,
v4+, of the WiX Toolset is desired, then a newer version will needed to be
explicitly installed as a step in the action before any cargo wix commands.

[!WARNING]
As of April 3rd, 2026, the GitHub Action Windows 11 ARM64 runner image does not
have the WiX Toolset installed. The Legacy or Modern variants will have
to be explicitly installed as a step in the action before any cargo wix
commands. See https://github.com/actions/partner-runner-images/blob/main/images/arm-windows-11-image.md#omitted-software.

Once the prerequisites have been installed, execute the following command to
install the cargo wix subcommand.

dosCopy
C:\> cargo install cargo-wix

Usage

Start a command prompt, such as cmd.exe, the Developer Prompt installed with
the Build Tools for Visual Studio 2026, Windows Terminal with Powershell,
or git bash, and navigate to the project's root folder. Run the subcommand:

dosCopy
C:\Path\to\Project> cargo wix init

This will create the wix folder in the project's root (along side the
Cargo.toml file) and then it will create the wix\main.wxs file from the WiX
Source (wxs) embedded within the subcommand. The generated wix\main.wxs file
can be used without modification with the following command to create an
installer for the project:

dosCopy
C:\Path\to\Project> cargo wix

The cargo wix subcommand without any arguments searches for a wix\main.wxs
file, relative to the project's root. It will compile the wix\main.wxs file
and then link the object file (target\wix\build\main.wixobj) to create the
Windows installer (MSI). The installer will be located in the target\wix
folder. All artifacts of the installer compilation and linking process are
placed within the target\wix folder. Paths in the wix\main.wxs file should
be relative to the project's root, i.e. the same location as the Cargo.toml
manifest file.

A different WiX Source (wxs) file from the wix\main.wxs file can be used by
specifying a path to it as an argument to the subcommand as follows:

dosCopy
C:\Path\to\Project> cargo wix Path\to\WiX\Source\File.wxs

You can also automatically run the installer after creating it by specifying the
--install argument:

dosCopy
C:\Path\to\Project> cargo wix --install

The print <template> subcommand, which prints one of the embedded templates to
stdout, can be used to create the main.wxs file. A WXS template file
specifically designed to work with this subcommand is embedded within the
cargo-wix binary during installation. Use the following commands to create a
WiX Source file and use it to create an installer with this subcommand.

dosCopy
C:\Path\to\Project> cargo wix print wxs > example.wxs
C:\Path\to\Project> cargo wix example.wxs

The WiX source file can be customized using a text editor, but modification of
the XML preprocessor variables should be avoided to ensure the cargo wix
command works properly.

To sign the installer (MSI) as part of the build process, ensure the signtool
command is available in the PATH system environment variable or use the
Developer Prompt that was installed with the Windows SDK, and use the sign
sub-subcommand as follows:

dosCopy
C:\Path\to\Project> cargo wix sign

Use the -h,--help flag to display information about additional options and
features.

dosCopy
C:\Path\to\Project> cargo wix -h

Tests

There are set environment variables that can be used to help debug a failing
test. The CARGO_WIX_TEST_PERSIST environment variable can be set to persist
the temporary directories that are created during integration tests. This allows
the developer to inspect the contents of the temporary directory. The
CARGO_WIX_TEST_PERSIST environment variable accepts any value. Unsetting the
environment variable will delete the temporary directories after each test.

The CARGO_WIX_TEST_LOG environment variable sets the log level while running
an integration test. It accepts an integer value between 0 and 5, with 0 turning
off logging, and 5 displaying all log statements (ERROR, WARN, INFO, DEBUG, and
TRACE). Log statements are not captured during tests, so this environment
variable should be used only when running an integration test in isolation to
prevent "swampping" the terminal/console with statements.

Finally, the CARGO_WIX_TEST_NO_CAPTURE environment variable accepts any value
and will display the output from the WiX Toolset compiler (candle.exe) and
linker (light.exe) when running an integration test. Similar to the
CARGO_WIX_TEST_LOG environment variable, this variable should only be used in
isolation to prevent "swamping" the terminal/console with the output from the
WiX Toolset commands. By default, the output is captured by the test not
cargo's test framework; thus, the cargo test -- --nocapture command has no
affect. Example of setting and unsetting all of the environment variables for
running a specific test:

dosCopy
C:\Path\to\Cargo\Wix> set CARGO_WIX_TEST_PERSIST=1
C:\Path\to\Cargo\Wix> set CARGO_WIX_TEST_LOG=5
C:\Path\to\Cargo\Wix> set CARGO_WIX_TEST_NO_CAPTURE=1
C:\Path\to\Cargo\Wix> cargo test <TEST NAME>
C:\Path\to\Cargo\Wix> set "CARGO_WIX_TEST_NO_CAPTURE="
C:\Path\to\Cargo\Wix> set "CARGO_WIX_TEST_LOG="
C:\Path\to\Cargo\Wix> set "CARGO_WIX_TEST_PERSIST="

where <TEST NAME> is replaced with the name of an integration test. The last
three lines/commands are optional and unsets the three environment variables to
avoid additional tests from also persisting, logging, and dumping output to the
terminal/console.

[!NOTE]
The -- --nocapture option is not needed to display the logging
statements or the output from the WiX Toolset compiler (candle.exe) and linker
(light.exe).

Here is the same example with Powershell:

powershellCopy
PS C:\Path\to\Cargo\Wix> $env:CARGO_WIX_TEST_PERSIST=1; $env:CARGO_WIX_TEST_LOG=5; $env:CARGO_WIX_TEST_NO_CAPTURE=1; 
PS C:\Path\to\Cargo\Wix> cargo test <TEST NAME>
PS C:\Path\to\Cargo\Wix> Remove-Item Env:\CARGO_WIX_TEST_PERSIST; Remove-Item Env:\CARGO_WIX_TEST_LOG; Remove-Item Env:\CARGO_WIX_TEST_NO_CAPTURE

License

The cargo-wix project is licensed under either the MIT license or Apache
2.0 license. See the LICENSE-MIT or LICENSE-APACHE files for more
information about licensing and copyright.