Windows Terminal — User Guide

Windows Terminal is Microsoft's modern, GPU-accelerated terminal application for Windows 10 and 11. It consolidates Command Prompt, PowerShell, WSL distributions, Azure Cloud Shell, and any command-line application into a single window with multiple tabs, split panes, Unicode/UTF-8 support, custom themes, and rich text rendering with a DirectX-based rendering engine. The project is open source under the MIT license.

This guide covers everything you need to install, configure, and use Windows Terminal effectively. For architecture internals, security hardening, and deep configuration reference, see the Admin Guide.

1. Quick Start

What You Get

Windows Terminal gives you a unified command-line experience across all your shells:

• Tabs and panes -- run multiple shells side by side in a single window
• GPU-accelerated rendering -- smooth scrolling and crisp text via DirectX
• Full Unicode and UTF-8 -- emoji, CJK characters, and complex scripts render correctly
• Custom themes and color schemes -- dark, light, and fully customizable appearances
• Automatic shell profiles -- detects installed shells (PowerShell, WSL, Azure Cloud Shell, Visual Studio Developer shells)
• Keyboard shortcuts -- extensive default bindings with full customization
• Quake mode -- a drop-down terminal that appears with a global hotkey
• Command palette -- search and execute any action by name
• Shell integration and suggestions -- command history, marks on the scrollbar, and intelligent suggestions

Tip

The fastest way to get started: install from the Microsoft Store, launch Windows Terminal, and press Ctrl+Shift+T to open a new tab or Alt+Shift+Plus to split the current pane vertically.

Prerequisites

• Windows 10 version 1903 (build 18362) or later, or Windows 11
• x64 or ARM64 processor

Install in 30 Seconds

winget install --id Microsoft.WindowsTerminal -e

Or open the Microsoft Store and search for "Windows Terminal."

Your First 60 Seconds

1. Launch Windows Terminal from the Start menu or by running wt in any shell.
2. The default profile (typically Windows PowerShell) opens automatically.
3. Press Ctrl+Shift+T to open a new tab with the default profile.
4. Press Alt+Shift+Plus to split the current pane vertically, or Alt+Shift+Minus to split horizontally.
5. Navigate between panes with Alt+Arrow keys.
6. Press Ctrl+Shift+P to open the Command Palette and explore available actions.
7. Press Ctrl+, to open the Settings UI and start customizing.

What to Try Next

• Configure a background image or acrylic transparency (see Configuration, Profile Settings)
• Set up quake mode for instant terminal access (see Common Tasks)
• Create custom keybindings (see Common Tasks, Custom Keybindings)
• Explore the full action list to discover capabilities (see Core Usage, Actions Reference)

2. Installation

System Requirements

Important

Windows Terminal requires the Windows 10 1903 update or newer. If you are on an older build, the application will not install. Check your version by running winver from the Run dialog.

Installation Methods

Microsoft Store (Recommended)

The Store provides automatic updates and is the simplest method:

1. Open the Microsoft Store application.
2. Search for "Windows Terminal."
3. Click Get or Install.
4. Once installed, launch from the Start menu or by typing wt in any shell.

winget

winget install --id Microsoft.WindowsTerminal -e

For the Preview build:

winget install --id Microsoft.WindowsTerminal.Preview -e

Chocolatey

choco install microsoft-windows-terminal

Scoop

scoop bucket add extras
scoop install windows-terminal

GitHub Releases (Manual)

1. Go to the Releases page on GitHub.
2. Download the .msixbundle file for the desired version.
3. Double-click the bundle to install, or use PowerShell:

Add-AppxPackage -Path .\Microsoft.WindowsTerminal_<version>.msixbundle

Warning

Manual installs from GitHub do not auto-update. You must check for and install new releases yourself. The Microsoft Store or winget methods are strongly preferred for staying current with security patches and bug fixes.

Preview Version

Windows Terminal Preview is a separate installation that receives new features before the stable release. Both the stable and preview versions can be installed side by side:

winget install --id Microsoft.WindowsTerminal.Preview -e

Verify Installation

wt --version

This prints the installed version. If the command is not found, ensure the installation completed and your PATH includes the Windows Apps directory.

Post-Install Verification

After installation, confirm that Windows Terminal is working:

1. Open the Start menu and type "Terminal" or "Windows Terminal."
2. The application should launch with your default shell profile.
3. Check the dropdown (the + button or the downward arrow next to it) to see detected profiles.
4. Press Ctrl+, to open Settings and verify the Settings UI loads.

Setting as Default Terminal (Windows 11)

On Windows 11, you can set Windows Terminal as the default terminal application for all console applications:

1. Open Settings > Privacy & security > For developers (or open Windows Terminal Settings).
2. Under Terminal, select Windows Terminal.
3. Alternatively, in Windows Terminal Settings, go to Startup and set Default terminal application to Windows Terminal.

Install Troubleshooting

"This app package is not supported for installation" error You are likely on an unsupported Windows version. Run winver and confirm you are on build 18362 or later.

Store install hangs or fails Try wsreset.exe to reset the Store cache, then retry. If that fails, use the winget method instead.

winget command not found Install the "App Installer" package from the Microsoft Store, which provides winget.

wt command not recognized after install Restart your shell session. If still not found, the install may not have created the app alias. Check Settings > Apps > App execution aliases and ensure "Windows Terminal" is enabled.

"Windows cannot install package" with .msixbundle Ensure Developer Mode is enabled (Settings > Privacy & security > For developers) or that sideloading is allowed on your device.

Uninstall and reinstall If the installation is corrupted, remove it first:

Get-AppxPackage Microsoft.WindowsTerminal | Remove-AppxPackage

Then reinstall using your preferred method.

3. Configuration

Windows Terminal stores its configuration in a JSON file called settings.json. You can edit this file directly for full control, or use the built-in Settings UI for a graphical experience.

Settings File Location

Open the settings file directly by pressing Ctrl+Shift+, (this opens the JSON file in your default editor), or open the Settings UI with Ctrl+,.

Tip

The settings.json file is validated against a JSON schema. Most editors (VS Code, for example) provide autocompletion and validation when the $schema property is present at the top of the file. If it is missing, add: "$schema": "https://aka.ms/terminal-profiles-schema"

Settings File Structure

The top-level structure of settings.json:

{
    "$schema": "https://aka.ms/terminal-profiles-schema",
    "defaultProfile": "{GUID-of-your-preferred-profile}",
    "profiles": {
        "defaults": {
            // Settings applied to ALL profiles
        },
        "list": [
            // Individual profile definitions
        ]
    },
    "schemes": [
        // Color scheme definitions
    ],
    "actions": [
        // Custom actions and keybindings
    ],
    "keybindings": [
        // Keychord-to-action-ID bindings
    ],
    "themes": [
        // Custom theme definitions
    ]
}

Global Settings

These properties control the entire application window, independent of any specific profile.

Warning and compatibility settings:

Rendering settings:

Experimental settings:

Profile Settings

Profile settings control the behavior and appearance of individual shell sessions. Settings placed under profiles.defaults apply to all profiles and can be overridden per-profile in the profiles.list array.

Identity and Shell

Appearance

Behavior

Unfocused appearance: Set unfocusedAppearance to an object with appearance properties (colorScheme, cursorShape, opacity, backgroundImage, etc.) to customize how a pane looks when it is not focused.

Experimental Profile Settings

Color Schemes

Color schemes define the 16 ANSI colors plus foreground, background, cursor, and selection colors. Each scheme is an object in the schemes array.

{
    "name": "My Custom Scheme",
    "foreground": "#D4D4D4",
    "background": "#1E1E1E",
    "cursorColor": "#FFFFFF",
    "selectionBackground": "#264F78",
    "black": "#000000",
    "red": "#CD3131",
    "green": "#0DBC79",
    "yellow": "#E5E510",
    "blue": "#2472C8",
    "purple": "#BC3FBC",
    "cyan": "#11A8CD",
    "white": "#E5E5E5",
    "brightBlack": "#666666",
    "brightRed": "#F14C4C",
    "brightGreen": "#23D18B",
    "brightYellow": "#F5F543",
    "brightBlue": "#3B8EEA",
    "brightCyan": "#29B8DB",
    "brightPurple": "#D670D6",
    "brightWhite": "#E5E5E5"
}

Built-in schemes: Campbell (default), Campbell Powershell, One Half Dark, One Half Light, Solarized Dark, Solarized Light, Tango Dark, Tango Light, Vintage.

Profiles can also use light/dark scheme switching:

"colorScheme": {
    "dark": "One Half Dark",
    "light": "One Half Light"
}

Themes

Themes control the non-terminal UI chrome: the title bar, tab row, and window frame. They are defined in the top-level themes array and referenced by the global theme property.

{
    "name": "My Theme",
    "tab": {
        "background": "#1E1E1E",
        "unfocusedBackground": "#2D2D2D",
        "showCloseButton": "hover",
        "iconStyle": "default"
    },
    "tabRow": {
        "background": "#1E1E1E",
        "unfocusedBackground": "#2D2D2D"
    },
    "window": {
        "applicationTheme": "dark",
        "useMica": false,
        "frame": "accent",
        "unfocusedFrame": "#444444"
    }
}

Theme color values can be #rrggbb, #rrggbbaa, "accent" (the OS accent color), "terminalBackground" (the active pane's background), or null.

The showCloseButton property accepts: "always", "hover", "never", "activeOnly".

The iconStyle property accepts: "default", "hidden", "monochrome".

On Windows 11, the frame and unfocusedFrame properties colorize the window border. The experimental.rainbowFrame property (boolean, default false) overrides these to cycle through all colors.

The useMica property enables the Windows 11 Mica material behind the entire window.

Note

The theme names "dark", "light", and "system" are reserved and cannot be used for custom themes. Use any other name.

4. Core Usage

Tabs

Tabs let you run multiple shell sessions in a single window.

Tip

You can set a custom color for any tab by right-clicking it and selecting "Color..." or by using the openTabColorPicker action. To set a permanent color per profile, add "tabColor": "#hexcolor" to the profile definition.

Panes

Panes split a tab into multiple views, each running its own shell session.

You can split with a specific profile:

{
    "command": {
        "action": "splitPane",
        "split": "right",
        "profile": "Ubuntu"
    },
    "keys": "ctrl+alt+u"
}

The size parameter (0.0 to 1.0) controls the new pane's proportion of the available space. The default is 0.5 (equal split).

Note

The moveFocus action supports directions beyond the four cardinals: "previous" goes to the most recently focused pane, "nextInOrder" and "previousInOrder" traverse panes sequentially, "first" focuses the first pane, and "parent" / "child" navigate the pane tree hierarchy.

Command Palette

The Command Palette provides searchable access to every action in Windows Terminal.

• Open in action mode: Ctrl+Shift+P -- search and execute actions by name
• Open in command-line mode: Assign a keybinding with "launchMode": "commandLine" to type wt subcommands directly

{
    "command": {
        "action": "commandPalette",
        "launchMode": "commandLine"
    },
    "keys": "ctrl+shift+enter"
}

Search

Search within the terminal scrollback buffer:

Copy and Paste

Copy supports several formatting options as action arguments:

• singleLine (boolean, default false) -- collapse all lines into one
• copyFormatting (boolean/string/array) -- include color/font formatting as HTML and/or RTF
• dismissSelection (boolean, default true) -- clear the selection after copying
• withControlSequences (boolean, default false) -- include raw ANSI escape sequences

Scrollback

The scrollUp and scrollDown actions accept a rowsToScroll parameter to scroll a specific number of lines.

Window Modes

Important

Quake mode summons a special window named _quake that drops down from the top of the screen. To make it work even when Terminal has no open windows, set "compatibility.allowHeadless": true in your global settings. Without this, quake mode only works while Terminal is already running.

Suggestions

The suggestions UI displays command history, tasks, and other sources as a filterable overlay:

{
    "command": {
        "action": "showSuggestions",
        "source": "all",
        "useCommandline": true
    },
    "keys": "ctrl+space"
}

The source parameter accepts "commandHistory", "tasks", "all", or an array of sources. When useCommandline is true, the current partially-typed command prepopulates the filter (requires shell integration).

Tasks and Snippets

Windows Terminal supports .wt.json files in your project directories. These files define named command snippets that appear in the suggestions UI when you are working in that directory:

{
    "$version": "1.0.0",
    "snippets": [
        {
            "input": "npm run build\r",
            "name": "Build project",
            "description": "Run the build script"
        }
    ]
}

Mark Mode and Selection

• Enter mark mode: Assign the markMode action. In mark mode, arrow keys move the cursor to create a selection without holding the mouse.
• Expand selection to word: expandSelectionToWord action
• Toggle block selection: toggleBlockSelection action
• Switch selection endpoint: switchSelectionEndpoint action
• Select all: selectAll action

URL Detection and Web Search

When experimental.detectURLs is true (the default), URLs in terminal output are underlined on hover and can be opened with Ctrl+Click.

The searchWeb action opens a browser with selected text as the query:

{
    "command": {
        "action": "searchWeb",
        "queryUrl": "https://www.google.com/search?q=%s"
    },
    "keys": "ctrl+shift+s"
}

The %s placeholder is replaced with the selected text.

Visual Customization

Opacity adjustment at runtime: Use the adjustOpacity action to change window transparency on the fly. With "relative": true, the opacity parameter is additive (e.g., +10 or -10).

Retro terminal effect: Set "experimental.retroTerminalEffect": true in a profile for a CRT-style appearance with scanlines and phosphor glow.

Custom pixel shaders: Set "experimental.pixelShaderPath" to the path of an HLSL file. The samples/PixelShaders/ directory in the Windows Terminal repository contains example shaders. This overrides the retro terminal effect.

Background images: Set backgroundImage, backgroundImageOpacity, backgroundImageStretchMode, and backgroundImageAlignment in a profile. Use the special value "desktopWallpaper" to mirror your desktop wallpaper.

Shader effects toggle: The toggleShaderEffects action enables/disables the pixel shader or retro effect at runtime.

Actions Reference

The following table documents every action available in Windows Terminal. Use these in the actions array of settings.json or bind them via the keybindings array.

Important

Actions with (none) in the Key Arguments column take no parameters. Actions marked (required) will fail silently if the required argument is missing. Use the Settings UI or JSON schema validation to catch configuration errors.

Keybindings

Keybindings are defined in the keybindings array and map key chords to action IDs. The format supports multi-key chords (pressing keys in sequence):

"keybindings": [
    { "keys": "ctrl+shift+t", "id": "Terminal.OpenNewTab" },
    { "keys": ["ctrl+k", "ctrl+p"], "id": "Terminal.CommandPalette" },
    { "keys": "ctrl+shift+w", "id": null }
]

Setting "id": null unbinds a key. Key chord modifiers are ctrl, alt, shift, and win. Keys can be named (backspace, delete, enter, esc, tab, space, up, down, left, right, home, end, pageup, pagedown, f1-f24, plus, minus, comma, period) or single characters.

Virtual key codes and scan codes are also supported: vk(nnn) and sc(nnn).

New Tab Menu Customization

The newTabMenu property controls the structure of the dropdown menu that appears when clicking the + button or the dropdown arrow:

"newTabMenu": [
    { "type": "profile", "profile": "PowerShell" },
    { "type": "profile", "profile": "Ubuntu" },
    { "type": "separator" },
    {
        "type": "folder",
        "name": "SSH Sessions",
        "icon": "\uE8AF",
        "entries": [
            { "type": "profile", "profile": "SSH Production" },
            { "type": "profile", "profile": "SSH Staging" }
        ]
    },
    { "type": "separator" },
    { "type": "remainingProfiles" }
]

Entry types:

• profile -- a specific profile by name or GUID
• folder -- a submenu with nested entries, an icon, and optional inline behavior ("auto" collapses single-entry folders)
• separator -- a visual divider
• remainingProfiles -- all profiles not already listed (use at most once)
• matchProfiles -- profiles matching a name, source, or commandline pattern
• action -- an action referenced by ID
• source -- profiles from a specific dynamic source

Caution

Using remainingProfiles more than once in the newTabMenu causes a crash (Access Violation in Settings.Model.dll). This is a known issue (GitHub #20124). Ensure you have exactly zero or one remainingProfiles entry.

5. Common Tasks

Custom Keybindings

To add or override keybindings, add entries to the actions or keybindings array in settings.json.

Example: Bind Ctrl+Shift+E to split right with the default profile:

"actions": [
    {
        "command": {
            "action": "splitPane",
            "split": "right"
        },
        "keys": "ctrl+shift+e",
        "id": "User.SplitRight"
    }
]

Example: Unbind a default keybinding:

"keybindings": [
    { "keys": "ctrl+shift+t", "id": null }
]

Example: Multi-key chord (press Ctrl+K, then Ctrl+O):

"keybindings": [
    { "keys": ["ctrl+k", "ctrl+o"], "id": "User.OpenCWD" }
]

Creating a WSL Profile

WSL distributions are usually auto-detected, but you can create one manually:

{
    "name": "Ubuntu 22.04",
    "commandline": "wsl.exe -d Ubuntu-22.04",
    "startingDirectory": "\\\\wsl$\\Ubuntu-22.04\\home\\username",
    "icon": "ms-appx:///ProfileIcons/{9acb9455-ca41-5af7-950f-6bca1bc9722f}.png",
    "colorScheme": "One Half Dark",
    "pathTranslationStyle": "wsl"
}

Setting pathTranslationStyle to "wsl" ensures that Windows paths dragged onto the terminal are automatically converted to /mnt/c/... format.

Creating an SSH Profile

{
    "name": "Production Server",
    "commandline": "ssh [email removed]",
    "icon": "\uD83D\uDD12",
    "colorScheme": "Solarized Dark",
    "tabColor": "#FF6347"
}

Setting Up Color Schemes

1. Find or create a scheme (many are available at community sites).
2. Add it to the schemes array in settings.json.
3. Reference it in your profile with "colorScheme": "SchemeName".
4. For automatic dark/light switching, use:

"colorScheme": {
    "dark": "One Half Dark",
    "light": "One Half Light"
}

Background Images

{
    "backgroundImage": "C:\\Users\\me\\Pictures\\wallpaper.jpg",
    "backgroundImageOpacity": 0.3,
    "backgroundImageStretchMode": "uniformToFill",
    "backgroundImageAlignment": "center"
}

Use "desktopWallpaper" as the value to mirror your current desktop wallpaper:

{
    "backgroundImage": "desktopWallpaper",
    "backgroundImageOpacity": 0.15
}

Quake Mode Setup

Quake mode provides a drop-down terminal that slides in from the top of the screen, toggled by a global hotkey. It works out of the box with Win+`` (backtick).

For the dropdown animation, use globalSummon with a dropdownDuration:

{
    "command": {
        "action": "globalSummon",
        "name": "_quake",
        "dropdownDuration": 200,
        "toggleVisibility": true,
        "monitor": "toMouse",
        "desktop": "toCurrent"
    },
    "keys": "win+`"
}

To keep quake mode running even after closing all other windows, set "compatibility.allowHeadless": true in global settings.

Warning

A known issue (GitHub #20056) causes quake mode to leave an empty tray icon after the window is closed. This is cosmetic and does not affect functionality.

Startup Actions

Launch multiple tabs and panes automatically when Terminal starts:

"startupActions": "new-tab -p \"PowerShell\" ; split-pane -H -p \"Ubuntu\" ; new-tab -p \"cmd\""

This uses the same syntax as wt command-line arguments.

Environment Variables Per Profile

{
    "name": "Dev Environment",
    "commandline": "powershell.exe",
    "environment": {
        "NODE_ENV": "development",
        "RUST_LOG": "debug",
        "PATH": "%PATH%;C:\\my-tools\\bin"
    }
}

Environment variable values can reference existing variables using %VARNAME% syntax.

Font Customization

"font": {
    "face": "Cascadia Code",
    "size": 14,
    "weight": "semi-light",
    "features": {
        "ss01": 1,
        "liga": 1
    }
}

Font features use four-character OpenType tags. Common ones:

• liga -- standard ligatures (e.g., != becomes a single glyph in supporting fonts)
• ss01 through ss20 -- stylistic sets (font-specific alternates)
• calt -- contextual alternates

Variable font axes use font.axes (e.g., {"wght": 350} for a non-standard weight).

Tab Colors

Set a persistent color per profile:

"tabColor": "#E06C75"

Or set it at runtime using the setTabColor action:

{
    "command": {
        "action": "setTabColor",
        "color": "#61AFEF"
    },
    "keys": "ctrl+shift+g"
}

Pass null for the color to reset to the default.

Elevating (Running as Administrator)

Set "elevate": true on a profile to always open it in an elevated context. When the current Terminal window is not elevated, a new elevated window is spawned with a UAC prompt.

Drag-and-Drop Path Translation

When dragging files from File Explorer into a WSL, Cygwin, or MSYS2 pane, set the pathTranslationStyle so that C:\Users\... is automatically converted:

The dragDropDelimiter setting controls the separator when dropping multiple files (default is a space).

Shell Integration and Marks

Shell integration lets Windows Terminal understand command boundaries, which enables:

• Automatic prompt marking (autoMarkPrompts)
• Scrollbar marks showing command locations (showMarksOnScrollbar)
• Scroll-to-mark navigation
• Suggestions from command history

Shell integration is configured in your shell's profile (e.g., ~/.bashrc, PowerShell $PROFILE). PowerShell 7.4+ includes built-in support. For other shells, follow the shell integration documentation for your specific shell.

Manual marks can be added with the addMark action and cleared with clearMark or clearAllMarks.

Exporting the Buffer

Save the entire terminal scrollback to a text file:

{
    "command": {
        "action": "exportBuffer",
        "path": "C:\\logs\\terminal-output.txt"
    },
    "keys": "ctrl+shift+x"
}

If path is empty, a file picker dialog opens.

Custom Pixel Shaders

Windows Terminal can apply custom HLSL pixel shaders to the terminal output. Example shaders are available in the samples/PixelShaders/ directory of the repository.

{
    "experimental.pixelShaderPath": "C:\\shaders\\my-effect.hlsl"
}

Toggle shader effects at runtime with the toggleShaderEffects action.

Multiple Actions on One Keybinding

Bind a single key chord to execute a sequence of actions:

{
    "command": {
        "action": "multipleActions",
        "actions": [
            { "action": "copy" },
            { "action": "closePane" }
        ]
    },
    "keys": "ctrl+shift+x"
}

Send Input (Macros)

Send arbitrary text or escape sequences to the shell:

{
    "command": {
        "action": "sendInput",
        "input": "git status\r"
    },
    "keys": "ctrl+shift+g"
}

Use \u001b for the Escape character in ANSI sequences:

{
    "command": {
        "action": "sendInput",
        "input": "\u001b[A"
    },
    "keys": "ctrl+shift+up"
}

Right-Click Context Menu

By default, right-clicking pastes from the clipboard (or copies the selection). To get a context menu instead:

"experimental.rightClickContextMenu": true

Clearing the Buffer

{
    "command": {
        "action": "clearBuffer",
        "clear": "all"
    },
    "keys": "ctrl+shift+k"
}

Options: "all" (screen + scrollback), "screen" (visible area only), "scrollback" (scrollback only).

Opening the Current Working Directory

The openCWD action opens File Explorer at the terminal's current working directory. This requires shell integration to be enabled so Terminal knows the current directory.

Persisted Window Layout

To restore your tabs and panes when Terminal reopens:

"firstWindowPreference": "persistedWindowLayout"

Terminal saves the window layout on close and restores it on the next launch.

Iterable Commands

Create commands that dynamically expand for each profile or color scheme:

{
    "iterateOn": "profiles",
    "name": "Switch to ${profile.name}",
    "command": {
        "action": "newTab",
        "profile": "${profile.name}"
    }
}

This generates one command palette entry for every profile.

Global Summon (Custom Hotkey to Summon Terminal)

Beyond quake mode, globalSummon provides fine-grained control over how the Terminal window is summoned:

{
    "command": {
        "action": "globalSummon",
        "desktop": "toCurrent",
        "monitor": "toMouse",
        "toggleVisibility": true
    },
    "keys": "ctrl+`"
}

Parameters:

• desktop: "any" (switch to the desktop where Terminal is), "toCurrent" (move Terminal to the current desktop), "onCurrent" (only summon if already on this desktop)
• monitor: "any", "toCurrent", "toMouse" (move to the monitor with the mouse cursor)
• name: summon a specific named window, or create one with that name if it does not exist
• dropdownDuration: milliseconds for a slide-in animation (0 for instant)
• toggleVisibility: when true, pressing the hotkey again minimizes the window

Running Fullscreen Without Tabs

Combine fullscreen and focus mode for a distraction-free experience:

"launchMode": "fullscreen",
"startupActions": ""

Or toggle at runtime:

{
    "command": {
        "action": "multipleActions",
        "actions": [
            { "action": "toggleFullscreen" },
            { "action": "toggleFocusMode" }
        ]
    },
    "keys": "f11"
}

Showing Fullscreen Tabs

By default, tabs are hidden in fullscreen. To keep them visible:

"showTabsFullscreen": true

Disabling Dynamic Profile Sources

To prevent Terminal from auto-detecting certain profile types:

"disabledProfileSources": [
    "Windows.Terminal.Azure",
    "Windows.Terminal.VisualStudio"
]

Valid sources: "Microsoft.WSL", "Windows.Terminal.Wsl", "Windows.Terminal.Azure", "Windows.Terminal.PowershellCore", "Windows.Terminal.VisualStudio".

6. Troubleshooting

Settings not applying after saving

Cause: JSON syntax error in settings.json, or editing the wrong file.

Solution:

1. Open settings.json in VS Code or another editor with JSON validation.
2. Look for red squiggly underlines indicating syntax errors (trailing commas, missing quotes, unclosed braces).
3. Confirm you are editing the correct file for your install method (Store vs. unpackaged path).
4. Windows Terminal hot-reloads settings -- no restart is needed unless the error prevented loading.

Prevention: Use the Settings UI (Ctrl+,) for simple changes, and always validate JSON before saving.

Fonts not rendering correctly or not found

Cause: The specified font is not installed system-wide, or the font name is misspelled.

Solution:

1. Open Windows Settings > Personalization > Fonts and confirm the font is installed.
2. Use the exact font family name (e.g., "Cascadia Code" not "CascadiaCode" or "Cascadia Code Regular").
3. If using a Nerd Font, the family name often includes "Nerd Font" (e.g., "FiraCode Nerd Font").
4. Reset to the default: "font": { "face": "Cascadia Mono" }.

Prevention: Test fonts in the Settings UI font picker, which shows only installed fonts.

GPU rendering issues (blank screen, artifacts, flickering)

Cause: Incompatible or outdated GPU drivers, or issues with the Direct3D 11 renderer.

Solution:

1. Update your GPU drivers to the latest version.
2. Try switching the graphics API: "rendering.graphicsAPI": "direct2d".
3. As a last resort, enable software rendering: "rendering.software": true.
4. If only partial rendering issues occur, try: "rendering.disablePartialInvalidation": true.

Prevention: Keep GPU drivers up to date.

Tip

If you experience flickering only in the tab bar, this is a known issue (GitHub #14384) that affects both stable and preview versions. Switching rendering.graphicsAPI may help in some cases.

WSL profiles not appearing

Cause: WSL is not installed, no distributions are installed, or the dynamic profile source is disabled.

Solution:

1. Confirm WSL is installed: wsl --list --verbose.
2. Install a distribution if none exists: wsl --install -d Ubuntu.
3. Check that "disabledProfileSources" in your settings does not include "Windows.Terminal.Wsl" or "Microsoft.WSL".
4. Restart Windows Terminal.

Prevention: Do not add WSL to the disabledProfileSources array unless you intentionally want to hide WSL profiles.

Error: Duplicate remainingProfiles in newTabMenu causes crash

Cause: Having more than one {"type": "remainingProfiles"} entry in the newTabMenu array triggers an Access Violation in Settings.Model.dll (GitHub #20124).

Solution:

1. Open settings.json and search for remainingProfiles.
2. Remove all but one instance.
3. Save and restart Terminal.

Prevention: Use at most one remainingProfiles entry in newTabMenu.

Ubuntu icon disappeared from tabs and dropdown

Cause: Profile icon path references an icon that is no longer available or the profile generator icon mapping changed (GitHub #20126).

Solution:

1. Manually set the icon for the affected profile in settings.json:

   "icon": "ms-appx:///ProfileIcons/{9acb9455-ca41-5af7-950f-6bca1bc9722f}.png"
   

2. Alternatively, use an emoji or a custom icon file path.

Quake mode leaves an empty tray icon

Cause: Known issue (GitHub #20056) where closing the quake window does not fully clean up the notification area icon.

Solution: Right-click the empty tray icon and dismiss it, or restart Windows Terminal. The icon is cosmetic and does not affect other windows.

Output slow for half a second, then fast

Cause: A rendering or input pipeline stall that resolves after the first buffer fill (GitHub #20113). May relate to shell startup scripts or the Direct3D swap chain initialization.

Solution:

1. Try "rendering.graphicsAPI": "direct2d".
2. Reduce shell startup overhead (remove heavy $PROFILE scripts).
3. If the issue persists, check for background antivirus scanning of the shell executable.

Half-width Katakana and (han)dakuten overlap

Cause: Combining characters in half-width Katakana are not correctly handled in the text layout engine (GitHub #18087).

Solution: No full fix yet. As a workaround, use full-width Katakana or set "compatibility.textMeasurement": "wcswidth" (may affect other Unicode rendering).

Arrow keys not working for on-screen keyboard in certain tools

Cause: Regression affecting virtual keyboard input in interactive CLI tools (GitHub #20122).

Solution: Use a physical keyboard. If a virtual keyboard is required, consider running the tool in conhost.exe directly.

New Actions / Quake Window broken

Cause: Settings migration issue where the actions or keybindings format is incompatible with a new version (GitHub #20119).

Solution:

1. Back up your settings.json.
2. Open Settings UI and check for error banners.
3. If errors are present, reset settings by deleting settings.json (it will be regenerated with defaults).
4. Re-apply your customizations.

SGR 2 (Faint/Dim) is ineffective on light themes

Cause: The dimming algorithm reduces color intensity, which is visually imperceptible against a light background (GitHub #20109).

Solution: No fix currently available. Use a dark color scheme for content that relies on faint/dim text rendering.

Alt+Tab adds an unwanted keyboard layout

Cause: When Terminal receives focus via Alt+Tab, the input system may register an additional keyboard layout (GitHub #14030).

Solution:

1. Check Windows Settings > Time & language > Language & region and remove unwanted keyboard layouts.
2. If the issue recurs, it is a Windows input method issue, not Terminal-specific.

The -d CLI parameter is not shown in help

Cause: The wt command-line help text does not document the -d (starting directory) flag, though it is functional (GitHub #9585).

Solution: The flag works despite being undocumented. Usage:

wt -d "C:\Projects"

OSC 7 notifications from non-host connections

Cause: Remote sessions (SSH, containers) send OSC 7 (current directory) sequences with a hostname that does not match the local machine (GitHub #20072).

Solution: Terminal currently processes all OSC 7 sequences regardless of host. If this causes incorrect "Open CWD" behavior, disable shell integration's OSC 7 output in your remote shell's configuration.

Tab bar flickering

Cause: A rendering race condition that causes the tab bar to flicker intermittently (GitHub #14384). Affects both stable and preview versions.

Solution:

1. Try different rendering.graphicsAPI values.
2. Update GPU drivers.
3. The issue is under active investigation by the Terminal team.

Warning

Do not modify rendering.software: true as a permanent solution for flickering -- it significantly degrades performance. Use it only for testing whether the issue is GPU-related.

Terminal crashes on startup

Cause: Corrupted settings.json or an incompatible extension.

Solution:

1. Rename settings.json to settings.json.bak.
2. Launch Terminal -- it will regenerate a default settings.json.
3. Gradually re-apply your customizations, testing after each change.
4. If the crash persists, check for corrupted MSIX packages:

   Get-AppxPackage Microsoft.WindowsTerminal | Remove-AppxPackage
   

   Then reinstall.

Missing ColorTool releases

Cause: ColorTool releases are no longer published separately from the main Terminal repository (GitHub #20129).

Solution: Use the color scheme management built into Windows Terminal itself, or build ColorTool from source (src/tools/ColorTool/ in the repository).

Acrylic not working when window is unfocused

Cause: By default, acrylic is disabled when the window loses focus to save GPU resources.

Solution: Set "compatibility.enableUnfocusedAcrylic": true in global settings.

wt command opens a new window instead of a tab

Cause: The default windowingBehavior is "useNew".

Solution: Set "windowingBehavior": "useExisting" to open new tabs in the most recently used window on the current virtual desktop, or "useAnyExisting" for any desktop.

Pasting triggers a large-paste warning for small text

Cause: The large-paste threshold is 5 KiB of characters.

Solution: If this is annoying for your workflow, disable it: "warning.largePaste": false. Similarly, "warning.multiLinePaste": false disables the newline warning.

Background image not displaying

Cause: The image path is invalid, the file format is unsupported, or the opacity is too low.

Solution:

1. Use an absolute path with escaped backslashes: "C:\\Users\\me\\image.jpg".
2. Supported formats: PNG, JPEG, GIF, BMP, ICO, TIFF.
3. Check that backgroundImageOpacity is greater than 0.
4. Try "backgroundImageStretchMode": "uniformToFill" if the image appears but is cropped unexpectedly.

Profiles from Visual Studio not appearing

Cause: The "Windows.Terminal.VisualStudio" profile source may be disabled, or Visual Studio is not properly installed.

Solution: Ensure disabledProfileSources does not include "Windows.Terminal.VisualStudio". Verify that Visual Studio Developer Command Prompt/PowerShell shortcuts exist in the Start menu.

Path with spaces not handled correctly

Cause: Some command-line arguments do not properly handle paths containing spaces (GitHub #20107).

Solution: Wrap paths in double quotes when using wt command-line arguments:

wt -d "C:\Program Files\My App"

Note

When editing settings.json, remember that JSON strings require backslashes to be escaped as \\. A path like C:\Users must be written as "C:\\Users".

Korean IME composing character hides adjacent character

Cause: A rendering issue with Korean IME composition (GitHub #20040, fixed in recent versions).

Solution: Update to the latest version of Windows Terminal.

Terminal window appears off-screen

Cause: The initialPosition setting references coordinates on a monitor that is no longer connected.

Solution:

1. Delete the initialPosition property from settings.json.
2. Set "centerOnLaunch": true to center the window on the primary display.
3. Alternatively, use Win+Left Arrow or Win+Right Arrow to snap the window to the current display.

Scrollback history lost after closing a tab

Cause: Terminal does not persist scrollback between sessions. When a tab or pane is closed, the buffer is discarded.

Solution: Use exportBuffer to save the scrollback before closing. For persistent logging, configure your shell to log output to a file.

Prevention: Set a generous historySize (default is 9001 lines) and use exportBuffer before closing important sessions.

Settings UI shows errors or crashes

Cause: Invalid or conflicting entries in settings.json that the Settings UI cannot parse.

Solution:

1. Open settings.json directly with a text editor.
2. Fix JSON syntax errors.
3. Look for deprecated property names and update them (e.g., "acrylicOpacity" should be "opacity").

7. FAQ

General

What is Windows Terminal? Windows Terminal is Microsoft's modern, open-source terminal application for Windows 10 and 11. It provides tabs, panes, GPU-accelerated rendering, Unicode support, and extensive customization. It is not a shell itself -- it is a host that runs shells like PowerShell, Command Prompt, WSL, and others.

Is Windows Terminal free? Yes. Windows Terminal is free and open source under the MIT license. Both the stable and preview versions are free.

What is the difference between Windows Terminal and Windows Terminal Preview? Windows Terminal Preview receives new features and changes before they are released to the stable version. Both can be installed side by side. Use Preview if you want early access to new features; use Stable for production reliability.

Does Windows Terminal replace Command Prompt or PowerShell? No. Windows Terminal is a terminal emulator that hosts these shells. Command Prompt (cmd.exe) and PowerShell continue to exist as separate programs. Terminal provides a modern interface for running them.

Can I use Windows Terminal on Windows Server? Windows Terminal requires Windows 10 1903 or later. Windows Server 2022 and later can run Terminal, but it may require manual installation via the MSIX bundle since the Microsoft Store may not be available.

What shells can Windows Terminal run? Any command-line application: PowerShell (5.1 and 7+), Command Prompt, WSL (all distributions), Azure Cloud Shell, Git Bash, Cygwin, MSYS2, SSH sessions, Python REPL, Node.js REPL, and more. If it runs in a console, Terminal can host it.

What is conhost.exe and how does it relate to Windows Terminal? conhost.exe is the legacy Windows console host. Windows Terminal and conhost share the same repository and many internal components (ConPTY, virtual terminal support), but Terminal provides the modern UI experience. ConPTY is the pseudo-console layer that lets Terminal host traditional console applications.

Installation

How do I check which version I have installed? Run wt --version from any command line, or open the About dialog from the dropdown menu or via the openAbout action.

How do I update Windows Terminal? Microsoft Store installs update automatically. For winget installs, run winget upgrade --id Microsoft.WindowsTerminal. For manual installs, download and install the latest .msixbundle from GitHub releases.

Can I run both stable and preview versions simultaneously? Yes. They are separate applications with separate settings files and can run at the same time.

Is Windows Terminal available for Windows 10 LTSC? Windows 10 LTSC 2019 (build 17763) does not meet the 1903 build requirement. LTSC 2021 (build 19044) and later support Windows Terminal.

Configuration

Where is my settings file? For Store/winget installs: %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json. For unpackaged installs: %LOCALAPPDATA%\Microsoft\Windows Terminal\settings.json. Press Ctrl+Shift+, to open it directly.

How do I reset settings to defaults? Delete or rename your settings.json file. Windows Terminal will regenerate it with default values on next launch.

Can I sync settings across machines? The settings file is a single JSON file that can be synced via cloud storage, symlinks, or version control. Place it in a synced folder and create a symbolic link at the expected path.

What is profiles.defaults for? Settings in profiles.defaults apply to every profile. They act as a base that individual profiles can override. This avoids duplicating settings like font configuration across every profile.

How do I make PowerShell 7 (pwsh) the default profile? Find the PowerShell 7 profile's GUID in the profiles list (or its name), then set "defaultProfile" to that GUID or name.

What happens if my settings.json has errors? Windows Terminal will attempt to load the file and will show a warning banner at the top of the window if errors are found. It falls back to default values for settings it cannot parse.

Can I have separate settings for stable and preview? Yes. They use different settings file paths and do not share configuration.

Appearance

How do I make the terminal transparent? Set "opacity" to a value less than 100 in the profile settings. For the frosted glass effect, also set "useAcrylic": true. You can adjust opacity at runtime with Ctrl+Shift+Scroll (when experimental.scrollToChangeOpacity is true).

How do I change the font? Set "font": { "face": "Font Name", "size": 14 } in your profile or in profiles.defaults. Use the Settings UI font picker to see available fonts.

What is the default color scheme? Campbell. It is a dark scheme included with Windows Terminal. Nine built-in schemes are available: Campbell, Campbell Powershell, One Half Dark, One Half Light, Solarized Dark, Solarized Light, Tango Dark, Tango Light, and Vintage.

Can I have different appearances when a pane is unfocused? Yes. Set the unfocusedAppearance property on a profile to an object containing appearance settings (color scheme, opacity, cursor shape, background image, etc.).

How do I use Mica material? In your theme definition, set "window": { "useMica": true }. This requires Windows 11.

How do I set a different color scheme for light and dark mode? Use the SchemePair syntax: "colorScheme": { "dark": "One Half Dark", "light": "One Half Light" }. The Terminal switches automatically based on the OS theme.

What cursor shapes are available? Six shapes: "bar" (default, a thin vertical line), "underscore" (a thin horizontal line at the bottom), "doubleUnderscore" (two horizontal lines), "filledBox" (a solid block), "emptyBox" (a hollow block), and "vintage" (a thick block with adjustable height via cursorHeight).

Usage

How do I split the screen into multiple panes? Press Alt+Shift+Plus for a vertical split or Alt+Shift+Minus for a horizontal split. Navigate between panes with Alt+Arrow keys.

How do I open a new tab with a specific profile? Press Ctrl+Shift+1 through Ctrl+Shift+9 to open by profile index (matching the order in the dropdown). Or use the dropdown menu to select a profile.

How do I copy and paste? Select text with the mouse, then press Ctrl+Shift+C (or just Ctrl+C if text is selected). Paste with Ctrl+Shift+V (or Ctrl+V). Enable "copyOnSelect": true to copy automatically on selection.

What is the Command Palette? Press Ctrl+Shift+P to open a searchable list of all available actions. Type to filter, then press Enter to execute.

What is quake mode? A drop-down terminal window that slides in from the top of the screen when you press Win+`` (backtick). It provides instant access to a terminal from any application. See Common Tasks for setup details.

How do I search within the terminal output? Press Ctrl+Shift+F to open the search box. Type your query and use the arrow buttons or findMatch bindings to navigate matches.

Can I run a command automatically when Terminal starts? Yes. Set "startupActions" in your global settings to a wt command-line string. For example: "new-tab -p PowerShell ; split-pane -p Ubuntu".

How do I send the same input to multiple panes? Broadcast input is not a built-in feature. You can simulate it using the sendInput action bound to keybindings, but true simultaneous broadcast is not supported as a native action.

How do I export my terminal output to a file? Use the exportBuffer action. Bind it to a key and optionally set a path. If no path is given, a file save dialog appears.

What are marks? Marks are positions in the scrollback buffer that you can jump between. They can be added manually via addMark or automatically via shell integration (autoMarkPrompts). Marks can optionally appear on the scrollbar with showMarksOnScrollbar.

What is the .wt.json file? A project-specific configuration file that defines command snippets (tasks). When placed in a directory, its snippets appear in the suggestions UI while you are working in that directory or its children.

Can I restore a closed tab? Yes, if you bind the restoreLastClosed action to a keybinding. It reopens the most recently closed tab or pane.

How does windowingBehavior work? "useNew" (default) always opens a new window. "useExisting" opens a new tab in the most recently used Terminal window on the current virtual desktop. "useAnyExisting" opens a tab in the most recently used window on any desktop.

How do I zoom a single pane to fill the window? Use the togglePaneZoom action. Press it again to restore the original pane layout.

Troubleshooting

Terminal opens but shows a blank or white screen. Try switching to "rendering.graphicsAPI": "direct2d" or enabling "rendering.software": true. Update your GPU drivers.

My custom settings are not taking effect. Check for JSON syntax errors. Windows Terminal silently ignores invalid JSON and falls back to defaults. Use a JSON validator or the Settings UI.

The wt command is not recognized. Restart your shell after installing Terminal. Check that the "Windows Terminal" app execution alias is enabled in Windows Settings > Apps > App execution aliases.

Terminal feels slow. Disable useAcrylic and any pixel shaders. Reduce historySize if it is set very high. Switch rendering.graphicsAPI to "direct3d11". Ensure the terminal is not running under a remote desktop session (GPU acceleration may not be available).

Can I downgrade to a previous version? Uninstall the current version, then install the desired version from a specific GitHub release .msixbundle. Microsoft Store does not support version pinning.