Windows Terminal Deployment & Usage Guide

Prerequisites

Component	Requirement	Notes
Operating System	Windows 10 version 2004 (build 19041) or later	Windows 11 recommended for full feature support
IDE	Visual Studio 2022 (Community, Professional, or Enterprise)	Latest version recommended
Git	Git for Windows	Required for submodules and LFS

Visual Studio Workloads & Components

Install the following via Visual Studio Installer:

Required Workloads:

Desktop development with C++
Universal Windows Platform development

Required Individual Components:

Windows 11 SDK (10.0.22621.0 or later)
C++ ATL for latest v143 build tools (x86 & x64)
C++ MFC for latest v143 build tools (x86 & x64)
C++ CMake tools for Windows
MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)

System Configuration

Enable Developer Mode on your Windows machine:

Open Settings → Privacy & Security → For developers
Toggle Developer Mode to On
Accept the warning dialog

Installation

1. Clone the Repository

git clone https://github.com/microsoft/terminal.git
cd terminal
git submodule update --init --recursive

2. Restore NuGet Packages

Open the solution in Visual Studio to automatically restore packages, or run:

nuget restore OpenConsole.sln

3. Verify Toolchain

Ensure MSBuild is available in your PATH (typically via Visual Studio Developer Command Prompt):

where msbuild

Configuration

Build Configurations

The solution supports the following configurations:

Configuration	Platform	Output
Debug	x64, x86, ARM64	Development build with symbols
Release	x64, x86, ARM64	Optimized build
AuditMode	x64	Static analysis build

Environment Variables (Optional)

Set the following if building outside Visual Studio:

$env:Platform="x64"
$env:Configuration="Debug"

Build & Run

Method 1: PowerShell (Recommended)

Open PowerShell in the repository root and run:

# Build and run Windows Terminal (Debug, x64)
Invoke-OpenTerminal

# Build specific configuration
Invoke-OpenTerminal -Configuration Release -Platform x64

# Build only (don't run)
Invoke-OpenTerminal -BuildOnly

Method 2: Command Prompt (MSBuild)

Open Developer Command Prompt for VS 2022:

# Build entire solution (Debug, x64)
msbuild OpenConsole.sln /p:Configuration=Debug /p:Platform=x64 /m

# Build specific project (Windows Terminal only)
msbuild src\cascadia\CascadiaPackage\CascadiaPackage.wapproj /p:Configuration=Release /p:Platform=x64

# Build Console Host only
msbuild src\host\exe\Host.EXE.vcxproj /p:Configuration=Debug /p:Platform=x64

Method 3: Visual Studio IDE

Open OpenConsole.sln in Visual Studio 2022
Select target platform (x64, x86, or ARM64) from the toolbar
Select configuration (Debug or Release)
Press F5 to build and debug, or Ctrl+Shift+B to build only

Running the Built Binaries

After building, binaries are located in:

Windows Terminal: .\src\cascadia\CascadiaPackage\bin\[Platform]\[Configuration]\AppX\
Console Host: .\bin\[Platform]\[Configuration]\

To run the locally built Terminal:

# From PowerShell (after Invoke-OpenTerminal build)
.\src\cascadia\CascadiaPackage\bin\x64\Debug\AppX\WindowsTerminal.exe

# Or launch via Visual Studio with F5 (enables debugging)

Deployment

Local Deployment (Sideloading)

Build the MSIX package for distribution:

# In PowerShell
msbuild src\cascadia\CascadiaPackage\CascadiaPackage.wapproj /t:Publish /p:Configuration=Release /p:Platform=x64 /p:AppxPackageDir=C:\TerminalPackages\

Install the generated MSIX:

Add-AppxPackage -Path "C:\TerminalPackages\CascadiaPackage_1.x.x.x_x64.msix"

Creating Distribution Packages

For GitHub Releases or manual distribution:

Build the solution in Release configuration
Navigate to src\cascadia\CascadiaPackage\AppPackages\
Locate the .msixbundle file for distribution

Note: If distributing manually, recipients may need to install the VC++ v14 Desktop Framework Package on older Windows 10 builds.

Microsoft Store Deployment

For forked versions or private distribution:

Associate the app with the Microsoft Store via Visual Studio (Project → Publish → Associate App with Store)
Create app packages via Project → Publish → Create App Packages
Upload .msixupload file to Microsoft Partner Center

Troubleshooting

Build Errors

Issue	Solution
Missing Windows SDK	Install Windows 11 SDK (10.0.22621.0) via Visual Studio Installer
ATL/MFC errors	Add C++ ATL and MFC components via Visual Studio Installer
NuGet restore failures	Run `nuget restore OpenConsole.sln` from Developer Command Prompt
Access denied during build	Ensure Developer Mode is enabled in Windows Settings

Runtime Issues

Issue	Solution
"Missing framework package" error	Install VC++ v14 Desktop Framework Package
Terminal looks like old console	You are running `conhost.exe` instead of Windows Terminal. Ensure you launched `WindowsTerminal.exe` from the build output, not the default console host
Cannot install MSIX	Ensure sideloading is enabled: `Settings → Privacy & Security → For developers → Sideload apps`

Debugging

To attach a debugger to the built Terminal:

Open Windows Terminal (built version)
In Visual Studio: Debug → Attach to Process
Select WindowsTerminal.exe or OpenConsole.exe (for the console host)
Set breakpoints in source code and trigger actions

For XAML/UI debugging, enable UI Debugging for XAML in Visual Studio options before attaching.

How to Deploy & Use microsoft/terminal