Terminal Auto‐Activation Explained

Setting: Terminal Auto-Activation Type

Id: python-envs.terminal.autoActivationType

Purpose: Controls how the Python Environments extension activates the selected Python environment when a new terminal is created in VS Code.

When auto-activation is enabled, the extension ensures python, pip, and related tools resolve to the interpreter in your chosen environment without requiring you to run activation commands manually.

---

Modes at a glance

• Command (default at the moment)
  Runs the environment’s activation command in the terminal right after it opens.

• Command Shell Startup (Will be the default once environment extension is rolled out fully to all of Python extension users)

  Activates your terminal without needing to send visual activation command in terminal. Meaning, terminal would be activated on creation. This is the recommended activation type to get Copilot terminal activated properly.

If you would like to revert all of the changes Python environment extension has made to your profile scripts, please run command python-envs.terminal.revertStartupScriptChanges

• Off
  Disables automatic activation entirely.

---

1) Command (default)

How it works

• When you open a new terminal in VS Code, the extension runs the activation command in that terminal session.
• The exact activation command depends on:
  • Your shell type (e.g., Bash, Zsh, PowerShell, Command Prompt)
  • Your OS type (Windows, macOS, Linux)
  • Your environment type (e.g., venv, Conda, Pipenv)
• After the command runs, python resolves to your selected environment.

How to debug Command mode

1. Open a new terminal in VS Code — you should see the activation command executed automatically at the top.
2. Determine the correct activation command by activating your environment manually outside of VS Code (using the correct command for your shell, OS, and environment type).
3. Compare:
   • The command VS Code executed
   • The command that works outside VS Code
4. If they differ:
   • Report the mismatch, or
   • Check additional settings that might influence the environment path (e.g., default interpreter path settings, environment variables).

---

2) Command Shell Startup

How it works

• The extension contributes environment variables which contains activate command specific to your environment and platform.
• Implementation differs by shell:

  • Bash, Zsh, Fish, PowerShell → When shell integration is enabled and properly injected, we activate by running the activate hooks from VS Code's shell integration script. In remote scenarios or for shells that do not support terminal shell integration, we prompt user for the modification of profile scripts or autorun entry in order to make this auto-activation to be effective and your prompt to be changed accordingly on terminal creation.

  • Command Prompt (cmd.exe) → Sets a Windows Registry autorun entry that runs a .bat script on shell start.

• Injected scripts will include comment markers like:

  # >>> vscode python
  # version: 0.1.0
  ...
  # <<< vscode python

• Once set, any terminal of that type opened in VS Code will have the environment active immediately.
• If at any time you want to remove these changes, run Python Envs: Revert Shell Startup Script Changes from the Command Palette.

For full details on how shell startup activation is implemented (including script examples for each shell type), see the (Maybe outdated, TODO: @anthonykim1 to update) Shell Startup Activation section of the README.

Why choose this

• Recommended for Copilot when they run commands in a new terminal and need the environment to be active before the first command executes.

How to debug Shell Startup

Command Prompt

1. Open Registry Editor and navigate to: HKEY_CURRENT_USER\Software\Microsoft\Command Processor
2. Look for the autorun value — it should point to a .bat file used for activation.
3. If missing, open a cmd terminal in VS Code, set the auto-activation type to Command Shell Startup, and reload the window to trigger injection.

---

appendix:

Information to include in a bug report

• Shell type (Bash, Zsh, PowerShell, Command Prompt, Fish)
• OS (Windows/macOS/Linux)
• Environment type (venv, Conda, Pipenv, etc.)
• Auto-Activation Type setting value (Command / Command Shell Startup / Off)
• Expected behavior
• Actual behavior
• If Command mode:
  • Activation command injected by VS Code
  • Activation command that works outside VS Code
• If Command Shell Startup mode:
  • Is terminal.integrated.shellIntegration.enabled set to true?
  • What is the quality of your shell integration? This should be visible when you hover over terminal tab, it should be either Rich, Basic, or None.
  • Are you on remote scenario, if so, what is your setup?
  • For Bash/Zsh/Fish/PowerShell: Is the snippet with # >>> vscode python present in the profile file?
    • Profile file path
  • For Command Prompt: Is autorun registry value present?
    • Path in autorun value
• Whether the issue happens in only one shell or multiple shells
• Whether it reproduces after Reload Window and opening a fresh terminal or restarting VS Code?