Appearance profile settings in Windows Terminal

The settings listed below are specific to each unique profile. If you’d like a setting to apply to all of your profiles, you can add it to the defaults section above the list of profiles in your settings.json file.

Color scheme

This is the name of the color scheme used in the profile. Color schemes are defined in the schemes object. More detailed information can be found on the Color schemes page.

Property name: colorScheme

Necessity: Optional

Accepts: Name of color scheme as a string

Default value: «Campbell»

Font face

This is the name of the font face used in the profile. The terminal will try to fallback to Consolas if this can’t be found or is invalid. To learn about the other variants of the default font, Cascadia Mono, visit the Cascadia Code page.

Property name: fontFace

Necessity: Optional

Accepts: Font name as a string

Default value: «Cascadia Mono»

Font size

This sets the profile’s font size in points.

Property name: fontSize

Necessity: Optional

Accepts: Integer

Default value: 12

Font weight

This sets the weight (lightness or heaviness of the strokes) for the profile’s font.

Property name: fontWeight

Necessity: Optional

Accepts: «normal» , «thin» , «extra-light» , «light» , «semi-light» , «medium» , «semi-bold» , «bold» , «extra-bold» , «black» , «extra-black» , or an integer corresponding to the numeric representation of the OpenType font weight

Default value: «normal»

Retro terminal effects

When this is set to true , the terminal will emulate a classic CRT display with scan lines and blurry text edges. This is an experimental feature and its continued existence is not guaranteed.

If experimental.pixelShaderPath is set, it will override this setting.

Property name: experimental.retroTerminalEffect

Necessity: Optional

Accepts: true , false

Default value: false

Configuration: Retro Command Prompt

Cursor

Cursor shape

This sets the cursor shape for the profile. The possible cursors are as follows: «bar» ( в”ѓ ), «vintage» ( в–ѓ ), «underscore» ( в–Ѓ ), «filledBox» ( в–€ ), «emptyBox» ( в–Ї ), «doubleUnderscore» ( ‗ )

Property name: cursorShape

Necessity: Optional

Accepts: «bar» , «vintage» , «underscore» , «filledBox» , «emptyBox» , «doubleUnderscore»

Default value: «bar»

Cursor height

This sets the percentage height of the cursor starting from the bottom. This will only work when cursorShape is set to «vintage» .

Property name: cursorHeight

Necessity: Optional

Accepts: Integer from 25-100

Background image

Background image path

This sets the file location of the image to draw over the window background. The background image can be a .jpg, .png, or .gif file. «desktopWallpaper» will set the background image to the desktop’s wallpaper.

Property name: backgroundImage

Necessity: Optional

Accepts: File location as a string or «desktopWallpaper»

Background image stretch mode

This sets how the background image is resized to fill the window.

Property name: backgroundImageStretchMode

Necessity: Optional

Accepts: «none» , «fill» , «uniform» , «uniformToFill»

Default value: «uniformToFill»

Background image source

Background image alignment

This sets how the background image aligns to the boundaries of the window.

Property name: backgroundImageAlignment

Necessity: Optional

Accepts: «center» , «left» , «top» , «right» , «bottom» , «topLeft» , «topRight» , «bottomLeft» , «bottomRight»

Default value: «center»

Background image source

Background image opacity

This sets the transparency of the background image.

Property name: backgroundImageOpacity

Necessity: Optional

Accepts: Number as a floating point value from 0-1

Default value: 1.0

Acrylic

Enable acrylic

When this is set to true , the window will have an acrylic background. When it’s set to false , the window will have a plain, untextured background. The transparency only applies to focused windows due to OS limitations.

Property name: useAcrylic

Necessity: Optional

Accepts: true , false

Default value: false

Acrylic opacity

When useAcrylic is set to true , this sets the transparency of the window for the profile. This accepts floating point values from 0-1.

Property name: acrylicOpacity

Necessity: Optional

Accepts: Number as a floating point value from 0-1

Default value: 0.5

Window

Padding

This sets the padding around the text within the window. This will accept three different formats: «#» and # set the same padding for all sides, «#, #» sets the same padding for left-right and top-bottom, and «#, #, #, #» sets the padding individually for left, top, right, and bottom.

Property name: padding

Necessity: Optional

Accepts: Values as a string in the following formats: «#» , «#, #» , «#, #, #, #» or value as an integer: #

Default value: «8, 8, 8, 8»

Scrollbar visibility

This sets the visibility of the scrollbar.

Property name: scrollbarState

Necessity: Optional

Accepts: «visible» , «hidden»

Color settings

Tab color

This sets the color of the profile’s tab. Using the tab color picker will override this color.

Property name: tabColor

Necessity: Optional

Accepts: Color as a string in hex format: «#rgb» or «#rrggbb»

Foreground color

This changes the foreground color of the profile. This overrides foreground set in the color scheme if colorScheme is set.

Property name: foreground

Necessity: Optional

Accepts: Color as a string in hex format: «#rgb» or «#rrggbb»

Background color

This changes the background color of the profile with this setting. This overrides background set in the color scheme if colorScheme is set.

Property name: background

Necessity: Optional

Accepts: Color as a string in hex format: «#rgb» or «#rrggbb»

Selection background color

This sets the background color of a selection within the profile. This will override the selectionBackground set in the color scheme if colorScheme is set.

Property name: selectionBackground

Necessity: Optional

Accepts: Color as a string in hex format: «#rgb» or «#rrggbb»

Cursor color

This sets the cursor color of the profile. This will override the cursorColor set in the color scheme if colorScheme is set.

Property name: cursorColor

Necessity: Optional

Accepts: Color as a string in hex format: «#rgb» or «#rrggbb»

Unfocused appearance settings

Unfocused appearance settings (Preview)

An object you can add to a profile that applies settings to the profile when it is unfocused. This setting only accepts appearance settings.

Property name: unfocusedAppearance

Necessity: Optional

Accepts: backgroundImage , backgroundImageAlignment , backgroundImageOpacity , backgroundImageStretchMode , cursorHeight , cursorShape , cursorColor , colorScheme , foreground , background , selectionBackground , experimental.retroTerminalEffect , experimental.pixelShaderPath

Example:

This feature is only available in Windows Terminal Preview.

Pixel shader effects

This setting allows a user to specify the path to a custom pixel shader to use with the terminal content. This is an experimental feature and its continued existence is not guaranteed. For more details on authoring custom pixel shaders for the terminal, see this documentation.

If set, this will override the experimental.retroTerminalEffect setting.

Property name: experimental.pixelShaderPath

Necessity: Optional

Accepts: A path to an .hlsl shader file, as a string

JSON fragment extensions in Windows Terminal

JSON fragment extensions are snippets of JSON that application developers can write to add new profiles to users’ settings, or even modify certain existing profiles. They can also be used to add new color schemes to users’ settings.

Structure of the JSON files

The JSON file should be split up into 2 lists, one for profiles and one for schemes. Here is an example of a json file that adds a new profile, modifies an existing profile, and creates a new color scheme:

The first item in the «profiles» list updates an existing profile, identifying the profile it wishes to update via the GUID provided to the «updates» field (details on how to obtain the GUID are in the next section). The second item in that list creates a new profile called «Cool Profile».

In the «schemes» list, a new color scheme called «Postmodern Tango Light» is defined, and can be subsequently referenced by the user in their settings file or in this JSON file itself (notice that «Cool Profile» uses this newly defined color scheme).

Of course, if the developer only wishes to add/modify profiles without adding color schemes (and vice-versa), only the relevant list needs to be present and the other list can be omitted.

How to determine the GUID of an existing profile

The only profiles that can be modified through fragments are the default profiles, Command Prompt and PowerShell, as well as dynamic profiles. To determine the GUID of the profile to be updated, use a Version 5 UUID generator with the following namespace GUID and name:

• The namespace GUID:
• The name of the profile to be updated

As a sanity check, a profile called ‘Ubuntu’ will get the generated GUID:

Minimum requirements for settings added with fragments

There are some minimal restrictions on what can be added to user settings using JSON fragments:

• For new profiles added via fragments, the new profile must, at a minimum, define a name for itself.
• For new color schemes added via fragments, the new color scheme must define a name for itself, as well as define every color in the color table (i.e. the colors «black» through «brightYellow» in the example image above).

Where to place the JSON fragment files

The location to place the JSON fragment files varies depending on the installation method of the application that wishes to place them.

Microsoft Store applications

For applications installed through the Microsoft Store (or similar), the application must declare itself to be an app extension. More details on app extensions can be found in the Microsoft Docs and the necessary section is replicated here. The appxmanifest file of the package must include:

Key things to note:

• The «Name» field must be com.microsoft.windows.terminal.settings for Windows Terminal to be able to detect the extension.
• The «Id» field can be filled out as the developer wishes.
• The «PublicFolder» field should have the name of the folder, relative to the package root, where the JSON files are stored (this folder is typically called «Public» but can be named something else if the developer wishes).
• Inside the public folder, a subdirectory called «Fragments» should be created, and the JSON files should be stored in that subdirectory.

Applications installed from the web

For applications installed from the web, there are 2 cases.

The first is that the installation is for all the users on the system. In this case, the JSON files should be added to the folder:

In the second case, the installation is only for the current user. In this case, the JSON files should be added to the folder:

C:\Users\ \AppData\Local\Microsoft\Windows Terminal\Fragments\

Note that both the ProgramData and LocalAppData folders are known folders that the installer should be able to access. If in either case, if the Windows Terminal\Fragments directory does not exist, the installer should create it.

General profile settings in Windows Terminal

The settings listed below are specific to each unique profile. If you’d like a setting to apply to all of your profiles, you can add it to the defaults section above the list of profiles in your settings.json file.

This is the name of the profile that will be displayed in the dropdown menu. This value is also used as the «title» to pass to the shell on startup. Some shells (like bash ) may choose to ignore this initial value, while others ( Command Prompt , PowerShell ) may use this value over the lifetime of the application. This «title» behavior can be overridden by using tabTitle .

Property name: name

Necessity: Required

Accepts: String

Command line

This is the executable used in the profile.

Property name: commandline

Necessity: Optional

Accepts: Executable file name as a string

Default value: «cmd.exe»

Starting directory

This is the directory the shell starts in when it is loaded.

Property name: startingDirectory

Necessity: Optional

Accepts: Folder location as a string

Default value: «%USERPROFILE%»

Example: Start the PowerShell profile in the GitHubRepos folder of your Documents directory by finding the powershell.exe profile and adding «startingDirectory»: «%USERPROFILE%/Documents/GitHubRepos»,

Example with WSL: When setting the starting directory for a Linux distribution installed via WSL, use the format: «startingDirectory»: «\\\\wsl$\\DISTRO NAME\\home\\USERNAME» , replacing with the placeholders with the proper names of your distribution. For example, «startingDirectory»: «\\\\wsl$\\Ubuntu-20.04\\home\\user1» .

Default behavior: When the startingDirectory value is not specified, you will get different results depending on where you launch Terminal:

• If you run Windows Terminal from the Start menu: C:\windows\system32
• If you run wt.exe from the Start menu: C:\windows\system32
• If you run wt.exe from Win+R: %USERPROFILE%
• If you run wt.exe from the explorer address bar: whatever folder you were looking at.

Backslashes need to be escaped. For example, C:\Users\USERNAME\Documents should be entered as C:\\Users\\USERNAME\\Documents .

This sets the icon that displays within the tab, dropdown menu, jumplist, and tab switcher.

Property name: icon

Necessity: Optional

Accepts: File location as a string, or an emoji

Example: By placing the icon image ubuntu.ico in the folder located at %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\RoamingState , you can display the icon by adding this line to the profile in your settings.json: «icon»: «ms-appdata:///roaming/ubuntu.ico» .

Tab title

If set, this will replace the name as the title to pass to the shell on startup. Some shells (like bash ) may choose to ignore this initial value, while others ( Command Prompt , PowerShell ) may use this value over the lifetime of the application. If you’d like to learn how to have the shell set your title, visit the tab title tutorial.

Property name: tabTitle

Necessity: Optional

Accepts: String

Hide profile from dropdown

If hidden is set to true , the profile will not appear in the list of profiles. This can be used to hide default profiles and dynamically generated profiles, while leaving them in your settings file. To learn more about dynamic profiles, visit the Dynamic profiles page.