Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 40 ยท Tasks and Terminal

Terminal Profiles and Shell Integration

Configure terminal profiles for PowerShell, Git Bash, WSL, zsh and bash in VS Code, set a default, pass arguments, and learn what shell integration adds.

A terminal in VS Code is just a shell process with a nice window around it. Which shell starts is decided by a terminal profile: a named recipe containing the program path, arguments, an icon and optional environment variables. Profiles let you keep PowerShell, Git Bash and WSL side by side on Windows, or bash, zsh and fish on macOS and Linux, and choose between them with one click.

After profiles, this lesson covers shell integration, a feature where VS Code watches the shell's prompt and commands to give you command decorations, command history and quick navigation.

The profile dropdown

Next to the + button in the terminal panel is a small arrow. It lists the detected profiles, plus Configure Terminal Settings and Select Default Profile. Choosing a profile from the list opens a terminal with that shell. Select Default Profile decides what plain Ctrl+Shift+` opens.

VS Code detects common shells automatically: PowerShell, Command Prompt, Git Bash and WSL distributions on Windows; the shells in /etc/shells on macOS and Linux.

Defining profiles in settings

Profiles live under terminal.integrated.profiles.<platform>, where the platform is windows, osx or linux. The default is chosen with terminal.integrated.defaultProfile.<platform>.

JSON
{
  "terminal.integrated.profiles.windows": {
    "PowerShell": { "source": "PowerShell", "icon": "terminal-powershell" },
    "Git Bash": { "source": "Git Bash" },
    "Dev Shell": {
      "path": "C:\\Program Files\\Git\\bin\\bash.exe",
      "args": ["--login", "-i"],
      "env": { "NODE_ENV": "development" },
      "icon": "terminal-bash"
    }
  },
  "terminal.integrated.defaultProfile.windows": "Git Bash"
}

A profile has these keys:

Key Meaning
source A built-in detector name such as "PowerShell" or "Git Bash"
path Full path to the executable (a string or a list tried in order)
args Command-line arguments passed to the shell
env Extra environment variables for that profile only
icon A codicon id such as terminal-bash
color A theme color for the tab, such as terminal.ansiBlue
overrideName Keep the profile name instead of showing the running process name

Use source when VS Code knows the shell, and path for anything else. Set a profile to null to hide a detected one:

JSON
{ "terminal.integrated.profiles.linux": { "sh": null } }

Profiles for specific jobs

Because a profile can carry env and args, it can work as a tiny environment manager. A "Python venv" profile on macOS, for example, might start zsh and source the virtual environment script. A "Prod read-only" profile can start a shell with a red tab color so nobody types into the wrong terminal by accident. Using color for dangerous contexts is a simple and effective safety trick.

Starting directory

terminal.integrated.cwd sets the folder a new terminal starts in; the default is the workspace root. You can use variables such as ${workspaceFolder} there. Tasks (see tasks.json) can set their own working directory through the options.cwd property.

Shell integration

Shell integration is a small script that VS Code injects into supported shells (bash, zsh, fish, PowerShell, and some others). It adds marks around each prompt, command and output, which lets the editor know where commands start and stop. With it you get:

  • Command decorations: a dot beside each command, colored by success or failure. Click it for options like Copy Output or Rerun Command.
  • Sticky scroll: the command that produced the visible output stays pinned at the top.
  • Command navigation: Ctrl+Up and Ctrl+Down move between commands.
  • Run Recent Command (Ctrl+Alt+R) and Go to Recent Directory (Ctrl+G).
  • Current working directory tracking, so a split terminal starts where the original is.
  • Better link detection for relative paths in output.

It is enabled by default (terminal.integrated.shellIntegration.enabled). If it breaks a heavily customized prompt, turn it off or load the script manually by adding a line in your shell's startup file:

Terminal
# in ~/.bashrc, only inside the VS Code terminal
[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path bash)"

The variable TERM_PROGRAM=vscode is set by VS Code, so a script can detect where it is running.

Troubleshooting

  • Terminal exits immediately with code 1. The path is wrong or args are not accepted. Run the same command in an external terminal to see the error.
  • PowerShell scripts blocked. On Windows, the default execution policy can stop .ps1 scripts such as activate.ps1. This is a system setting; ask whether changing it is appropriate for you before you do.
  • Slow shell start. Heavy profile scripts (.bashrc, .zshrc, PowerShell $PROFILE) slow every terminal. Time them outside VS Code too.
  • Different PATH than expected. A terminal inherits VS Code's environment. If you installed a tool and the terminal cannot find it, restart VS Code completely.

Runnable stand-ins

The code below is not part of VS Code. The first resolves which profile would be used by default; the second shows the decision behind a simple prompt marker used by shell integration.

JS Stand-in: resolve the default profile

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Stand-in: command decorations from exit codes

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which setting chooses the shell that opens by default on Windows?

    defaultProfile.<platform> names the profile used by default. The old shell settings were replaced by profiles.
  2. 2. What does a profile's env key do?

    env is applied to the shell process started from that profile only.
  3. 3. What does shell integration add?

    By marking prompts and commands it enables decorations, sticky scroll, history and navigation.
  4. 4. How can a startup script detect it runs in the VS Code terminal?

    VS Code sets TERM_PROGRAM=vscode in its terminals.

Summary

  • A terminal profile names a shell, its arguments, environment, icon and color.
  • Configure terminal.integrated.profiles.<platform> and defaultProfile.<platform>.
  • Use source for known shells and path otherwise; null hides one.
  • Shell integration adds decorations, sticky scroll, history and navigation.
  • Most terminal problems are a wrong path, arguments, a slow startup file or a stale PATH.

Next: Tasks and tasks.json