How to Configure Windows Terminal for Use With WSL

Windows Terminal auto-detects installed WSL distros and creates profiles for them automatically, but a handful of deliberate configuration steps make the actual day-to-day experience meaningfully better.

Step 1: confirm Windows Terminal detected your WSL distro

Windows Terminal → dropdown arrow next to the + tab button →
  your installed WSL distro should appear automatically as a profile

If a distro doesn’t appear, confirm it’s actually installed and registered (wsl --list --verbose from PowerShell) — Windows Terminal detects distros dynamically from WSL’s own registered distro list.

Step 2: set your WSL distro as the default profile

Windows Terminal → Settings → Startup →
  Default profile → select your WSL distro

This makes opening a new Windows Terminal window or tab launch directly into your WSL distro’s shell, rather than PowerShell or Command Prompt.

Step 3: install and configure a Nerd Font for icon glyph support

Windows Terminal → Settings → your WSL profile →
  Appearance → Font face → select an installed
  Nerd Font variant

If your shell prompt or TUI tools use icon glyphs, a properly installed Nerd Font is a prerequisite — without one, these glyphs render as broken boxes or question marks regardless of any other configuration.

Step 4: set a sensible default starting directory

Windows Terminal → Settings → your WSL profile →
  General → Starting directory →
  leave blank/default to use the distro's own
  default (typically your Linux home directory)

Leaving this at its default generally gives the most intuitive behavior — opening directly into your Linux-side home directory rather than a Windows-side path.

Step 5: configure the color scheme

Windows Terminal → Settings → your WSL profile →
  Appearance → Color scheme

Windows Terminal ships several built-in schemes and supports importing custom ones — check here first if colors look wrong specifically inside Windows Terminal but correctly elsewhere.

Step 6: enable a comfortable scrollback buffer size

Windows Terminal → Settings → your WSL profile →
  Advanced → History size

A larger scrollback buffer is genuinely useful for reviewing long build or log output without needing to redirect it to a file first.

Step 7: set up keyboard shortcuts that don’t conflict with your shell or tmux

Windows Terminal → Settings → Actions →
  review default keybindings for conflicts with
  anything your shell or tmux configuration relies on

Windows Terminal has its own global keybindings (new tab, split pane) that can occasionally overlap with shell or tmux prefix keys — worth checking specifically if you experience unexpected keybinding conflicts.

Step 8: use Windows Terminal’s own pane splitting alongside or instead of tmux

Alt+Shift+D   split pane (default keybinding)

Windows Terminal supports native pane splitting — some users prefer this for simple cases and reserve tmux specifically for session persistence across disconnects, since Windows Terminal’s own panes don’t survive closing the terminal application itself.

Step 9: verify everything works together

echo $TERM
neofetch    # or any TUI tool, to visually confirm
            # rendering and colors look correct

Why configuring this once is worth the up-front time

A properly configured Windows Terminal profile — correct default distro, working font, sensible color scheme — removes a whole category of small daily friction points (broken icons, wrong colors, opening into the wrong shell) that otherwise resurface repeatedly across every new terminal window until deliberately fixed.

Where Windows Terminal itself came from

Microsoft announced Windows Terminal at its Build 2019 developer conference in May 2019, with source code appearing publicly on GitHub on May 3 that same year — positioned explicitly as a modern, GPU-accelerated replacement for the aging Windows Console, supporting tabs and, critically for this guide, PowerShell, Command Prompt, and WSL distros side by side in one application. The first stable 1.0 release followed about a year later, on May 19, 2020, and starting with Windows 11 build 21337, Windows Terminal ships pre-installed rather than requiring a separate Microsoft Store download — meaning a genuinely current Windows 11 installation already has the tool this entire guide configures, with nothing extra to install first.

Step 10: launch straight into your WSL profile from the Windows command line

wt -p "Ubuntu"
wt -p "Ubuntu" -d "\\wsl$\Ubuntu\home\username\projects"

The -p flag launches Windows Terminal directly into a named profile, and -d sets the starting directory for that specific launch — genuinely useful for a shortcut, a script, or a “Open Terminal Here” context-menu entry that should land directly in your WSL distro at a specific project path, rather than requiring you to open Windows Terminal and navigate manually every time. Multiple new-tab/split-pane invocations can even be chained in a single wt command, separated by an escaped semicolon, to open several panes or tabs with different profiles in one launch.

Step 11: edit settings.json directly for anything the Settings UI doesn’t expose

Windows Terminal → dropdown arrow next to the + tab button →
  hold Alt and click a profile, or use "Open JSON file"

Windows Terminal’s Settings UI covers the common cases, but the underlying settings.json file supports options the graphical settings page doesn’t surface at all — certain advanced per-profile behaviors, custom color scheme definitions beyond the bundled presets, and fine-grained keybinding actions. Since the GUI and the JSON file both read and write the same underlying configuration, editing the JSON directly for something specific and then confirming it in the GUI afterward is a normal, supported workflow, not a workaround.

Because settings.json is plain, version-controllable text, it’s also reasonable to keep a personal copy in a dotfiles repository and symlink it into place on a new machine — a meaningfully faster way to reproduce a specific, deliberately tuned Windows Terminal configuration than manually re-clicking through every Settings UI page again from scratch.

Related:

Sources: