This guide addresses some of the common errors and obstacles you might encounter when using Windows Terminal.

Opening the settings does nothing (or opens an unexpected application)

If you select thesettings button in the dropdown, the Terminal tries to open the settings file,settings.json. This action causes the OS to launch your configured.json file editor. This editor might be Visual Studio, Notepad, or some other unexpected application. If your machine doesn't have a configured.json editor, the OS eventually shows you theHow do you want to open this file dialog.

Set your WSL distribution to start in the home~ directory when launched in older versions of Windows Terminal

By default, thestartingDirectory of a profile is%USERPROFILE% (C:\Users\<YourUsername>). This path is a Windows path. For WSL distributions running a new version of Windows Terminal, the file systems can enter~ to set this home path. In older versions of Windows Terminal, you can use/home/<Your Ubuntu Username> to directly refer to your home folder. For example, the following setting launches the "Ubuntu-20.04" distribution in its home file path:

{    "name": "Ubuntu-20.04",    "commandline" : "wsl -d Ubuntu-20.04",    "startingDirectory" : "/home/<Your Ubuntu Username>"}

If you're using a very early version of Windows Terminal, WSL might require using the\\wsl$\ prefix when referring to a distribution's home path for thestartingDirectory setting. For example, the following setting launches the "Ubuntu-18.04" distribution in its home file path:

{    "name": "Ubuntu-18.04",    "commandline" : "wsl -d Ubuntu-18.04",    "startingDirectory" : "//wsl$/Ubuntu-18.04/home/<Your Ubuntu Username>"}

Setting the tab title

To have the shell automatically set your tab title,visit the set the tab title tutorial. If you want to set your own tab title, open thesettings.json file and follow these steps:

1. In the profile for the command line of your choice, add"suppressApplicationTitle": true to suppress any title change events that the shell sends. Addingonly this setting to your profile sets the tab title to the name of your profile.

2. If you want a custom tab title that isn't the name of your profile, add"tabTitle": "TITLE". Replace "TITLE" with your preferred tab title.

Command line arguments in PowerShell

To learn how command-line arguments work in PowerShell, see theCommand line arguments page.

Command line arguments in WSL

To learn how command-line arguments work in WSL, see theCommand line arguments page.

Problem settingstartingDirectory

If your profile ignores thestartingDirectory setting, first check the syntax in yoursettings.json file. To help you check this syntax,"$schema": "https://aka.ms/terminal-profiles-schema" is automatically injected. Some applications, likeVisual Studio Code, use that injected schema to validate your JSON file as you make edits.

If your settings are correct, you might be running a startup script that sets the starting directory of your terminal separately. For example, PowerShell has its own separate concept of profiles. If you change your starting directory in a PowerShell profile, it takes precedence over the setting defined in Windows Terminal.

Alternatively, if you run a script by using thecommandline profile setting, you might be setting the location in that script. Similar to PowerShell profiles, your commands in the script take precedence over thestartingDirectory profile setting.

The purpose ofstartingDirectory is to launch a new Windows Terminal instance in the given directory. If the terminal runs any code that changes its directory, check that code.

Ctrl+= doesn't increase the font size

If you use a German keyboard layout, you might run into this problem.Ctrl+= gets deserialized asCtrl+Shift+0 if your main keyboard layout is set to German. This mapping is correct for German keyboards.

More importantly, the app never receives theCtrl+Shift+0 keystroke. This issue happens because Windows reservesCtrl+Shift+0 if you have multiple keyboard layouts active.

If you want to disable this feature so thatCtrl+= works properly, follow the instructions for "Change Hotkeys to Switch Keyboard Layout in Windows 10" in thisblog post.

Change the 'Switch Keyboard Layout' option to 'Not Assigned' (or off ofCtrl+Shift), then selectOK and thenApply.Ctrl+Shift+0 should now work as a key binding and is passed through to the terminal.

On the other hand, if you use this hotkey feature for multiple input languages, you canconfigure your own custom key binding in yoursettings.json file.

The text is blurry

Some display drivers and hardware combinations don't handle scroll and dirty regions without blurring the data from the previous frame. To mitigate this problem, add a combination ofthese global rendering settings to reduce the strain placed on your hardware caused by the terminal text renderer.

My colors look strange! There are black bars on my screen!

Windows Terminal 1.2 and later versions have an improved understanding of certain application color settings. Because of this improved understanding, we removed a number of compatibility blocks that resulted in a poor user experience. Unfortunately, a small number of applications might experience issues.

We keep this troubleshooting item up-to-date with the list of known issues and their workarounds.

Black lines in PowerShell (5.1, 6.x, 7.0)

Terminal, when coupled with PowerShell's line editing libraryPSReadline, might draw black lines across the screen. These miscolored regions extend across the screen beyond your prompt wherever there are command parameters, strings, or operators.

PSReadline version2.0.3 contains a fix for this issue. If you're using the prerelease version of PSReadline, note that a fix isn't yet available.

To update to the newest version of PSReadline, run the following command:

Update-Module PSReadline

Why aren't my emojis appearing as icons in the jumplist?

Only images linked from a file location can be rendered as profile icons in the jumplist. The jumplist doesn't support emojis for icons.

Technical notes

Applications that use theGetConsoleScreenBufferInfo family of APIs to retrieve the active console colors in Win32 format and then try to transform them into cross-platform VT sequences (for example, by transformingBACKGROUND_RED to\x1b[41m) might interfere with Terminal's ability to detect what background color the application is trying to use.

Choose either Windows API functionsor VT sequences for adjusting colors. Don't mix them.

Keyboard service warning

Starting in Windows Terminal 1.5, the Terminal displays a warning if the "Touch Keyboard and Handwriting Panel Service" is disabled. The operating system needs this service to properly route input events to the Terminal application (as well as many other applications on Windows). If you see this warning, follow these steps to re-enable the service:

1. In the run dialog, runservices.msc

   

2. Find the "Touch Keyboard and Handwriting Panel Service"

   

3. Open the "Properties" for this service

   

4. Change the "startup type" to "Automatic"

   

5. SelectOk, and restart the PC.

After restarting the machine, the service auto-starts, and the dialog no longer appears.

Why do I see blinking or flashing when using a Git Bash command line?

You might notice blinking or flashing when using a Git Bash command line inside Windows Terminal. This behavior is actually by design. The Terminal obeys what Git Bash tells it to do (settingbell-style tovisible, causing a flash to associate with the bell response), but this behavior can be distracting. To fix this issue, open the.inputrc file for your Git Bash with a text editor. This file is likely located in the pathC:\Program Files\Git\etc. To open the file with the Nano text editor, use the command:nano ~/.inputrc.

Change the default:

# none, visible or audibleset bell-style visible

Set thebell-style to eithernone oraudible to remove the visible flash:

set bell-style none

Press Ctrl + O and Ctrl + X to save and exit.

How do I reset my settings in Windows Terminal back to the default settings?

To reset your settings back to the original default settings, delete yoursettings.json file. This action causes Windows Terminal to regenerate asettings.json file with the original default settings.

Why is Acrylic opacity not making my Windows Terminal background transparent?

You can set the transparency of a terminal window with theuseAcrylic property. There are a few reasons why your opacity setting might not work for Acrylic, including:

• As a system-wide policy, acrylic is only enabled for the foreground window. If you activate any other window than the Terminal, the Terminal's acrylic turns off.
• Acrylic doesn't work if your GPU hardware doesn't support it. If you're running an app in a virtual machine (VM) or over remote desktop, acrylic likely doesn't work.
• The operating system disables acrylic for a number of reasons, like being in power saver (low-battery) mode or when accessing a machine by using Remote Desktop.

Why does my mouse pointer disappear when I hover over a window and start typing?

This cursor auto-hiding behavior is by design, but you can disable it. Search in Windows Settings forMouse settings >Additional Mouse Settings >Mouse Properties >Pointer Options > and uncheckHide pointer while typing. You might need to restart your Windows Terminal for this change to take effect.