WinUI 3: How to Fix “Unable to Load DLL Microsoft.ui.xaml.dll”

If your WinUI 3 application builds successfully but crashes when you try to run it with an error such as:

Unable to load DLL 'Microsoft.ui.xaml.dll' or one of its dependencies:
The specified module could not be found. (0x8007007E)

The problem is usually not your XAML code. In many cases, the application cannot find or initialize the Windows App SDK runtime required by WinUI 3.

This becomes especially common when working with an unpackaged application, running the executable outside Visual Studio, or changing the application's packaging configuration.

Microsoft's current Windows Developer FAQ specifically identifies this error and explains that unpackaged applications need the Windows App SDK runtime installed and initialized correctly.

The Problem

You may have a perfectly valid WinUI 3 application:

public partial class App : Application
{
    public App()
    {
        InitializeComponent();
    }
}

The project builds successfully, but when you run the application it fails before the main window appears.

The exception may look similar to:

System.DllNotFoundException:
Unable to load DLL 'Microsoft.ui.xaml.dll' or one of its dependencies:
The specified module could not be found. (0x8007007E)

At first glance, it is tempting to assume that the DLL is missing from your project's output directory. That is not necessarily the real problem.

The important question is:

Is your application correctly configured to use the Windows App SDK runtime?

Why Does This Error Happen?

WinUI 3 is part of the Windows App SDK. Your application therefore needs access to the Windows App SDK runtime when it starts.

The exact deployment requirements depend on whether your application is:

• Packaged with MSIX
• Packaged with external location
• Unpackaged
• Framework-dependent
• Self-contained

For an unpackaged framework-dependent application, the Windows App SDK runtime must be installed on the target machine and the application must initialize access to it.

First Check: Is Your App Packaged or Unpackaged?

Open your .csproj file and look for:

<WindowsPackageType>None</WindowsPackageType>

If you have this property, your application is configured as unpackaged.

<PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net10.0-windows10.0.26100.0</TargetFramework>

    <WindowsPackageType>None</WindowsPackageType>
</PropertyGroup>

The exact target framework and SDK versions may differ depending on your project.

Fix 1: If You Are Developing a Packaged WinUI 3 App

The standard WinUI 3 Visual Studio templates are configured to build packaged applications using MSIX by default.

If you accidentally launch the wrong profile, the runtime may not be available in the way you expect.

In Visual Studio, check the launch profile.

For a packaged application, use the MSIX/package launch profile rather than simply launching the executable directly.

After changing the profile:

1. Clean the solution.
2. Rebuild the solution.
3. Start the application using the MSIX/package profile.

Fix 2: If You Intentionally Use an Unpackaged App

If your project contains:

<WindowsPackageType>None</WindowsPackageType>

you have additional runtime requirements.

Unpackaged applications must initialize access to the Windows App SDK runtime before using Windows App SDK features such as WinUI 3.

For many modern .NET projects, the recommended approach is Windows App SDK auto-initialization.

<PropertyGroup>
    <WindowsPackageType>None</WindowsPackageType>
</PropertyGroup>

Fix 3: Install the Matching Windows App SDK Runtime

This is one of the most important steps when running an unpackaged application on another computer.

Installing the Microsoft.WindowsAppSDK NuGet package does not automatically mean that every target machine has the required framework runtime installed.

For framework-dependent unpackaged applications, the Windows App SDK runtime must be deployed to the target machine.

The runtime version should match the Windows App SDK version your application requires.

Why Does It Work on My Development PC?

This is a very common question:

“It works perfectly on my computer, but when I copy the EXE to another computer, it crashes.”

Your development machine may already have the Windows App SDK runtime installed.

Your second machine may not.

Development PC

WinUI 3 Application
       ↓
Windows App SDK Runtime
       ↓
Runs successfully

Compared with:

New PC

WinUI 3 Application
       ↓
Windows App SDK Runtime missing
       ↓
Microsoft.ui.xaml.dll error

This is why deployment testing on a clean machine is important.

Fix 4: Use Self-Contained Deployment

If you don't want the target computer to require a separately installed Windows App SDK runtime, you can consider self-contained deployment.

For example:

<PropertyGroup>
    <WindowsPackageType>None</WindowsPackageType>
    <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
</PropertyGroup>

This causes the Windows App SDK runtime to be included with the application output.

The advantage is straightforward:

Application
    +
Windows App SDK runtime
    ↓
Deploy together

The disadvantage is that your application becomes larger.

Framework-Dependent vs Self-Contained

Framework-Dependent

Your App
   +
Installed Windows App SDK Runtime

Advantages:

• Smaller application deployment
• Runtime can be serviced separately
• Less duplicated runtime content

Disadvantage:

• Runtime must be installed and configured correctly

Self-Contained

Your App
   +
Windows App SDK Runtime
   ↓
Single deployment payload

Advantages:

• Easier runtime dependency management
• No separate Windows App SDK runtime installation required

Disadvantages:

• Larger deployment
• Application updates carry the runtime payload

A Practical .csproj Example

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <OutputType>WinExe</OutputType>

        <TargetFramework>
            net10.0-windows10.0.26100.0
        </TargetFramework>

        <TargetPlatformMinVersion>
            10.0.22621.0
        </TargetPlatformMinVersion>

        <RootNamespace>MyWinUIApp</RootNamespace>

        <ApplicationManifest>
            app.manifest
        </ApplicationManifest>

        <Platforms>x86;x64;ARM64</Platforms>

        <RuntimeIdentifiers>
            win-x86;win-x64;win-arm64
        </RuntimeIdentifiers>

        <WindowsPackageType>None</WindowsPackageType>

        <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
    </PropertyGroup>

</Project>

Your actual project may contain additional WinUI, MSBuild, packaging, and NuGet properties. Do not replace your entire project file blindly.

The important concepts are:

<WindowsPackageType>None</WindowsPackageType>

<WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>

What About Bootstrap.Initialize()?

You may see older examples that manually call a bootstrap API.

Windows App SDK supports explicit bootstrapper initialization for advanced scenarios where you need more control over runtime initialization.

However, don't add manual initialization simply because you saw it in an old example.

Modern .NET Windows App SDK projects can use auto-initialization for the standard scenario.

Don't Mix Packaging Configurations

Another common mistake is accidentally combining incompatible deployment assumptions.

Before debugging the DLL error, determine your intended deployment model:

Do I want MSIX?

        OR

Do I want an unpackaged EXE?

Then configure the project accordingly.

A Simple Troubleshooting Checklist

1. Check the .csproj configuration.
2. Determine whether the application is packaged or unpackaged.
3. If packaged, use the correct MSIX launch profile.
4. If unpackaged, make sure the Windows App SDK runtime is installed.
5. Check that the runtime version matches your application.
6. Check Windows App SDK runtime initialization.
7. Consider self-contained deployment if appropriate.
8. Test on a clean machine.

Common Mistakes

1. Copying Only the EXE

A WinUI 3 application isn't necessarily a standalone executable just because an .exe file exists.

If you're using framework-dependent unpackaged deployment, the Windows App SDK runtime is still a dependency.

2. Installing the Wrong Runtime Version

Your application depends on a specific Windows App SDK version. Deploy the runtime corresponding to the version your application requires.

3. Adding Random DLLs to the Output Folder

Don't solve the problem by randomly copying Microsoft.ui.xaml.dll from another computer. Fix the Windows App SDK deployment configuration instead.

4. Testing Only on the Development Machine

Your development PC may already contain Visual Studio, Windows SDK, Windows App SDK runtime, Visual C++ Redistributable, and other required components.

A clean machine exposes missing dependencies much more reliably.

5. Using Old Bootstrapper Examples

Windows App SDK deployment guidance has evolved. Check the current Microsoft documentation before manually adding bootstrapper code.

Why This Error Is Often a Deployment Problem

If the application builds successfully but fails before the WinUI window appears, investigate runtime and deployment dependencies before debugging your XAML.

Build succeeds
      ↓
Application starts
      ↓
WinUI runtime loads
      ↓
Microsoft.ui.xaml.dll
      ↓
Runtime dependency missing
      ↓
Application crashes

Best Practice for WinUI 3 Deployment

For a production WinUI 3 application, decide on your deployment model early.

If you're using MSIX:

WinUI 3
   ↓
MSIX
   ↓
Windows App SDK dependencies
   ↓
Install

If you're distributing an unpackaged application:

WinUI 3
   ↓
Unpackaged
   ↓
Runtime deployment
   +
Runtime initialization

If you want to reduce external runtime dependencies:

WinUI 3
   ↓
Unpackaged
   ↓
Self-contained
   ↓
Application + Windows App SDK runtime

Quick Fix Summary

Packaged application

Use the MSIX/package launch profile and make sure the package is built and deployed correctly.

Unpackaged framework-dependent application

Make sure:

<WindowsPackageType>None</WindowsPackageType>

is configured correctly, the Windows App SDK runtime is installed on the target machine, and the runtime is initialized.

Unpackaged self-contained application

Consider:

<WindowsPackageType>None</WindowsPackageType>
<WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>

Conclusion

The “Unable to load DLL Microsoft.ui.xaml.dll” error in WinUI 3 can look like a missing DLL problem, but the underlying issue is often Windows App SDK runtime deployment or initialization.

The first thing to determine is whether your application is packaged or unpackaged.

For packaged applications, verify the MSIX deployment and Visual Studio launch profile.

For unpackaged applications, verify:

• Windows App SDK runtime installation
• Runtime version
• Bootstrap or auto-initialization
• WindowsPackageType
• Deployment architecture

If you don't want the target machine to have a separately installed Windows App SDK runtime, self-contained deployment can be an option.

The most important lesson is:

Don't randomly copy Microsoft.ui.xaml.dll. Fix the Windows App SDK deployment model that your application actually uses.

FAQ

Why does Microsoft.ui.xaml.dll work on my PC but not another PC?

Your development PC may already have the required Windows App SDK runtime installed. An unpackaged framework-dependent application requires that runtime on the target machine as well.

Does installing the Microsoft.WindowsAppSDK NuGet package install the runtime for users?

Not by itself. For unpackaged framework-dependent deployment, the Windows App SDK runtime must be deployed to the target machine.

What does WindowsPackageType None mean?

It configures the project for an unpackaged deployment model. It is also part of the standard auto-initialization approach for unpackaged applications.

Should I use self-contained deployment?

It can be useful when you want the Windows App SDK runtime included with your application instead of requiring a separate runtime installation. The trade-off is a larger deployment payload.

Should I manually call Bootstrap.Initialize()?

Not necessarily. Modern .NET Windows App SDK projects can use auto-initialization. Explicit bootstrapper initialization is primarily useful when you need advanced control over runtime initialization.

Recommended Microsoft Documentation

• Windows Developer FAQ — Microsoft Learn
• Windows App SDK deployment guide for unpackaged apps
• Distribute an unpackaged WinUI 3 app
• Windows App SDK deployment overview
• Windows App SDK bootstrapper tutorial