I'm currently available for contract work & technical writing opportunities. Hire me

A guide to customising the Windows Terminal

The Windows terminal provides a much improved command line experience in Windows 10. It’s packed with useful features like GPU acceleration, tabs, panes, themes, and shortcuts, along with full support for different environments such as PowerShell, Command Prompt, and Windows Subsystem for Linux. In this article, I’ll describe a few ways to tailor the terminal experience to your needs along with tips and tricks to make your experience much better.

The Windows terminal app is available on the Microsoft Store. If you open the store and search for “Windows terminal”, it should be the first item on the list. It’s also available on its GitHub releases page but you will miss out on automatic updates if you install it from there. You can also install the Preview version if you want to be on the bleeding edge of features.

Microsoft store showing Windows Terminal

Once installed, launch the terminal. The interface is quite straightforward with tabs at the top and a dropdown menu for switching between the different profiles. By default, you get a profile for PowerShell, the Command prompt, any WSL distributions you have installed, and Microsoft Azure.

Windows terminal default view

You can open the Settings through the dropdown menu or by pressing Ctrl + , on your keyboard. From v1.7, the Windows terminal settings no longer open in a JSON file by default as was the case in earlier releases. A new settings UI has been developed and it’s now the default way to manage your preferences although it’s only a frontend for the underlying JSON file which can be still be accessed by pressing Ctrl + Shift + ,.

Windows terminal settings user interface in version 1.7

The underlying JSON configuration file can be accessed by clicking on the settings cog icon

Launch the terminal with a keyboard shortcut

The easiest way to bind the Windows terminal to a keyboard shortcut is to pin it to the task bar and press the Win key plus the number corresponding to the position of the program on the taskbar. For example, Win + 3 launches or focuses the terminal window on my computer.

Windows taskbar showing position of Windows terminal

I don’t like this method because it flashes the taskbar on my screen briefly (it’s hidden by default) while the switch is being made which I find distracting. So I prefer to use AutoHotkey to run or raise a Windows terminal instance with the help of this script.

The steps to get this working are:

  • Create a new text file with a .ahk extension.
  • Copy and paste the above script into the file.
  • Double click the file to run it.

Once that’s done, you’ll be able to bring up the Windows terminal with a keystroke. The linked script uses Win + `, but you can change it to your preferred key binding. Instead of running the script manually everytime, you can follow these instructions to make it run automatically on system startup.

Launch the terminal from Windows Explorer

You can launch the Windows terminal from the File Explorer by typing wt and Enter in the address bar. This will launch a new terminal window in your default user directory. To specify the current directory instead, use wt -d ..

File explorer showing Windows Terminal command

Additionally, you can right click on a directory in File Explorer and select “Open in Windows Terminal”. This will launch Windows Terminal with your default profile in the selected directory.

File explorer showing Launch in Windows Terminal option

Change the default profile

The default profile is what appears when you launch a Windows terminal instance or open a new tab. It should be initally set to a Windows Powershell profile but you can easily change it to some other profile such as the one for your preferred WSL distribution. Achieving this can be done by updating the value of the defaultProfile property in the settings.json file with the guid of your preferred profile. It can also be changed through the settings UI as shown below:

Windows terminal startup profile

Customise the tab settings

From v1.5, the Windows terminal tab switcher displays currently open tabs in a vertical list, navigable with the keyboard or mouse. This feature had to be activated in earlier versions by setting the useTabSwitcher property (now deprecated) to true.

Windows terminal tab switcher mode enabled

Tab switcher mode enabled in Windows Terminal v1.5 and later

You can opt out of the tab switcher experience by setting tabSwitcherMode to false or "disabled". When the tab switcher is disabled, pressing ctrl + tab or ctrl + shift + tab will switch tabs in a similar manner to most web browsers. If you want to control the order of the tabs in the tab switcher, you can set tabSwitcherMode to mru or inOrder which will list the tabs either in most recently used order or in order of their layout in the terminal.

settings.json
// Enables the tab switcher
"tabSwitcherMode": "mru",
"tabSwitcherMode": "inOrder"

// Disables the tab switcher
"tabSwitcherMode": "disabled"
Windows Terminal tab switcher settings

You can also search your open tabs with the tabSearch command but you have to create a binding for it first. This is useful if you usually have several tabs open at same time.

settings.json
{
    "actions": [
        { "command": "tabSearch", "keys": "ctrl+t" }
    ]
}

Customise the profile settings

The profile settings can be accessed through the profiles property in the settings.json file. If you want any setting to apply to all profiles, add it to the defaults property. Otherwise, add it to the relevant object in the list array.

settings.json
"defaults":
{
    // SETTINGS TO APPLY TO ALL PROFILES
},
"list":
[
    // PROFILE OBJECTS
]
Windows terminal settings ui showing profile settings

In the settings UI, each profile has its own entry on the sidebar below the global settings.

Change the starting directory

The starting directory for all shells is the Windows User directory ("%USERPROFILE%") by default, but you probably want the Linux home directory instead in your WSL profiles. You can add the startingDirectory property to your WSL distribution profile object as shown below to override this setting.

settings.json
{
    "guid": "{07b52e3e-de2c-5db4-bd2d-ba144ed6c273}",
    "hidden": false,
    "name": "Ubuntu-20.04",
    "source": "Windows.Terminal.Wsl",
    "startingDirectory": "\\\\wsl$\\Ubuntu-20.04\\home\\<username>"
}
Windows terminal settings UI showing starting directory for a WSL distribution

Hide a profile

To hide a profile from the dropdown menu, set the hidden property on the profile object to true.

settings.json
{
    "guid": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}",
    "hidden": true,
    "name": "Azure Cloud Shell",
    "source": "Windows.Terminal.Azure"
}
Windows terminal settings UI showing hide from dropdown option

Turn off the scroll bar

If you primarily use tmux, you may want to turn off the scroll bar for your WSL profile by setting the scrollbarState option to hidden.

settings.json
{
    "guid": "{07b52e3e-de2c-5db4-bd2d-ba144ed6c273}",
    "hidden": false,
    "name": "Ubuntu-20.04",
    "source": "Windows.Terminal.Wsl",
    "startingDirectory": "\\\\wsl$\\Ubuntu-20.04\\home\\<username>",
    "scrollbarState": "hidden"
}
Windows terminal settings UI showing scrollbar setting

This setting can be found under the Appearance tab for the profile

You can read the documentation for the profile settings to learn about all the options available to you.

Customise the background

It’s possible to customise the Windows terminal with background images. The backgroundImage property can be set to an image URL, a local file path or the desktopWallpaper string (from v1.5), and the image in question may be of JPEG, PNG or GIF formats. You also have control over related settings such as opacity, alignment, and stretching. These settings can be configured globally for all profiles or per profile.

settings.json
{
    "backgroundImage": "https://images.unsplash.com/photo-1554110397-9bac083977c6?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=2100&q=80",
    "backgroundImageOpacity": 0.4,
    "backgroundImageAlignment": "center"
}
Windows Terminal background settings
Background image set on Windows terminal

You can also use animated GIFS if you’re so inclined:

GIF

The Terminal also supports the acrylic effect in Windows 10 which can be enabled by setting useAcrylic to true. The transparency of the effect can be controlled with acrylicOpacity (accepts a floating point between 0 and 1). You can use these settings with or without a background image.

settings.json
{
    "useAcrylic": true,
    "acrylicOpacity": 0.5
}
Windows Terminal showing acrylic settings
Windows Terminal showing acrylic effect

Customise the colour scheme

The terminal comes with a few colour schemes that you can choose from. They are accessible via the color schemes menu. You can choose your preferred global colour scheme from this menu, or add new ones if you don’t like any of the defaults.

Windows terminal showing colour schemes menu

If you prefer to set a different colour scheme per profile, the relevant setting is under the Appearance tab for each profile.

Windows terminal showing profile colour scheme

The profile colour scheme overrides the global one for the specific profile

The same can be achieved in the settings.json file through the colorScheme option. This option can be set globally for all profiles or per profile.

settings.json
{
    "guid": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
    "name": "Windows PowerShell",
    "commandline": "powershell.exe",
    "colorScheme": "Campbell Powershell",
    "useAcrylic": true,
    "acrylicOpacity": 0.9
}
Windows Terminal showing Campbell Powershell colour scheme

The Campbell Powershell colour scheme

Adding custom colour schemes is also easier through the settings.json file. All you need to do is define the colour scheme object in the schemes array section of the file. A great place to source for colour schemes is the Windows Terminal Themes website. You can preview each available theme and, when you find one you like, click the Get theme button to copy its JSON object to your clipboard.

Windows Terminal Themes website

Place the JSON object in the schemes array, then set the colorScheme property to the theme name (or use the settings UI to set the theme). The new theme should take effect once you save the file.

settings.json
{
    "schemes": [
        {
            "name": "AdventureTime",
            "black": "#050404",
            "red": "#bd0013",
            "green": "#4ab118",
            "yellow": "#e7741e",
            "blue": "#0f4ac6",
            "purple": "#665993",
            "cyan": "#70a598",
            "white": "#f8dcc0",
            "brightBlack": "#4e7cbf",
            "brightRed": "#fc5f5a",
            "brightGreen": "#9eff6e",
            "brightYellow": "#efc11a",
            "brightBlue": "#1997c6",
            "brightPurple": "#9b5953",
            "brightCyan": "#c8faf4",
            "brightWhite": "#f6f5fb",
            "background": "#1f1d45",
            "foreground": "#f8dcc0"
        }
    ]
}
Windows Terminal showing AdventureTime theme

The AdventureTime colour scheme

Make your prompt pretty with Starship

Starship provides a customised command prompt experience that displays some handy information to give you context of what you’re doing. It supports all the popular shells on Linux, macOS, and Windows including Bash, Fish, Zsh, Powershell, and others, making it possible to get a consistent prompt even if you often switch between different shells.

Windows Terminal showing starship prompt in Fish shell

This Fish prompt is styled using Starship

Before you install Starship, you need to make sure a Nerd font is installed on your computer first to prevent broken glyphs from ruining your prompt. A good option is Cascadia Code (the default Windows terminal font) which can be downloaded from its GitHub releases page. Once downloaded, extract the zip, and install all the font files contained in the ttf/static folder.

Windows explorer showing Cascadia Code PL font installation

Next, change the fontFace property in your profile settings to Cascadia Code PL.

settings.json
{
    "fontFace": "Cascadia Code PL"
}
Windows terminal profile font setting

Afterwards, go ahead and install Starship by following the instructions for your preferred shell. Once you’re done, create a configuration file in the ~/.config directory:

$ mkdir -p ~/.config && touch ~/.config/starship.toml

Open the starship.toml file, and paste in the following contents:

starship.toml
add_newline = false

[character]
success_symbol = "[⚡](bold green) "
error_symbol = "[❌](bold red) "

[aws]
disabled = true

[time]
disabled = true

[cmd_duration]
disabled = true

[directory]
truncation_length = 8

[hostname]
disabled = true

[nodejs]
symbol = "🤢"

[battery]
full_symbol = "🔋 "
charging_symbol = "⚡️ "
discharging_symbol = "💀 "
disabled = false

[git_status]
conflicted = "🚩"
ahead = "💨"
behind = "😰"
diverged = "😵"
untracked = "🤷"
stashed = "📦"
modified = "📝"
staged = '[++\($count\)](green)'
renamed = "👅"
deleted = "💥"

[shell]
fish_indicator = "🦈"
bash_indicator = "🌞"
disabled = false

The above represents my current configuration which should give you a prompt that looks similar to the previous screenshot. You can head over to the Starship docs to learn more about the available options, then tweak your configuration file as needed.

Split panes for multiple shells at once

Windows Terminal showing split panes

PowerShell top, Ubuntu bottom

The Windows terminal supports splitting a tab into multiple panes. This makes it easy to multitask without having to switch tabs. I use tmux for this purpose in WSL so it’s not something I rely on often, but it’s handy to have especially if you need to work out of Windows and WSL.

The default shortcuts to split a pane horizontally and vertically are Alt + Shift + - and Alt + Shift + = respectively. You can also split a pane using the command palette which can be accessed with Ctrl + Shift + p:

Windows terminal showing command palette

If you hold down the Alt key and press the new tab button on one of the profiles in the terminal dropdown menu, it would also auto split the active window or pane. To switch focus between panes, hold down Alt and use your arrow keys or click on the desired pane. Resizing the focused pane is done by holding down Alt + Shift and one of the arrow keys. Closing a pane can be done with Ctrl + Shift + W.

Customise the hotkeys

All the hotkeys for Windows Terminal commands can be customised through the actions property (formerly keybindings) in the settings.json file. If you inspect the defaults.json file for your terminal (by holding the Alt key while clicking the Settings menu), you’ll see all the default key bindings organised in several categories in the root level actions array.

Visual Studio Code showing defaults.json file with the actions property highlighted

You can add a new hotkey for an action by copying the relevant binding object from the defaults.json file to the settings.json file, and changing the keys property in the object. If you modify the defaults.json file directly, your changes will be lost when the program updates. For example, the bindings for splitting panes can be customised as shown below:

settings.json
{
    "actions": [
        { "command": { "action": "splitPane", "split": "vertical" }, "keys": "alt+v" },
        { "command": { "action": "splitPane", "split": "horizontal" }, "keys": "alt+h" }
    ]
}

The above lines add new bindings for the splitPane action, but the original bindings will remain active. To remove a default key binding, assign the key to the unbound command as shown below:

settings.json
{
    "actions": [
        { "command": { "action": "splitPane", "split": "vertical" }, "keys": "alt+v" },
        { "command": { "action": "splitPane", "split": "horizontal" }, "keys": "alt+h" },
        { "command": "unbound", "keys": "alt+shift+-" },
        { "command": "unbound", "keys": "alt+shift+=" }
    ]
}

Windows terminal also gives you the ability to send input commands to your shell with a key stroke. This is handy for commonly used commands. Here’s an example that binds Alt + G to sending a command that navigates to the root of the working tree in a git repo:

settings.json
{
    "actions": [
        { "command": {"action": "sendInput", "input": "cd (git rev-parse --show-toplevel)"}, "keys": "alt+g" }
    ]
}

The full list of commands and their options can be found in the Actions documentation.

Set up custom SSH profiles

It can be handy to automatically SSH into remote machines through the Windows Terminal. This can be done by setting up a new custom profile per machine.

settings.json
{
    "guid":  "{4b8d0cfe-e8be-4ae6-a4ad-88efd65b0880}",
    "hidden":  false,
    "name":  "Failed Experiments",
    "commandline":  "wsl ssh user@localhost",
    "icon": "🤡"
}

The guid field must be unique amongst the profiles. You can make changes to an exisiting one or generate it online. Regarding the icon, you can use an emoji character (v1.5 or later) or type the path to a suitable image file. Once you save the settings file, you should see your new entry similar to the screenshot below.

Windows Terminal Showing Custom Profile

Once you click the entry, it will automatically connect to the remote server in your preferred Linux distribution.

Customise the startup layout

Windows terminal launches with a single tab and a single pane using your default profile, but you can customise this behaviour through command line arguments. Here’s an example that launches the terminal with a custom layout of three split panes in a single tab. The panes are running a WSL profile, a PowerShell profile, and a Command Prompt profile respectively.

wt; split-pane -p "Windows PowerShell"
Windows terminal showing split panes

Here’s a breakdown of the above command:

  • wt on its own launches a new window with a single tab and a single pane with the default profile. Each command after wt must be separated with a semicolon.
  • split-pane splits the current pane into two defaulting to auto if you don’t specify a direction (-H or -V). The -p flag allows you to specify the the type of profile you want to open by name or guid.

After you have defined your preferred startup layout, you can bind it to a hotkey using AutoHotkey or create a new Windows shortcut and pin it to your desktop or taskbar.

Conclusion

In this post, we discussed several ways to customise the Windows Terminal. I hope it has helped you improve your workflow and productivity on the command line. If you have any more tips, please share them in the comments section below.

Thanks for reading, and happy coding!