VS Code Profiles & Workspaces — Multi-Environment Setup Guide

In this tutorial, you'll learn about VS Code Profiles & Workspaces. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

VS Code Profiles and Workspaces let you create isolated, project-specific configurations that automatically load the right extensions, settings, and tasks for every project you work on. Instead of manually enabling and disabling extensions, you define a profile for each role.

What You'll Learn

You'll create and manage VS Code profiles for different development roles, build multi-root workspaces that combine related projects, share workspace settings with your team via .code-workspace files, and automate environment switching so each project gets exactly the tools it needs.

Why Profiles and Workspaces Matter

A frontend developer needs one set of extensions and a backend developer needs another. Without profiles, your VS Code installation accumulates dozens of extensions that slow startup and clutter the interface. Profiles solve this by isolating your configuration per role or project. Workspaces extend this by grouping related folders, tasks, and launch configurations into a single window.

Doda Browser's web team uses a shared workspace file that loads frontend, API, and documentation folders with the correct extensions for each sub-project.

Learning Path

flowchart LR
  A[VS Code Basics] --> B[Workspace Config]
  B --> C[Profiles Deep Dive
You are here]
  C --> D[Team Workspace Sharing]
  C --> E[Multi-Root Workspaces]
  style C fill:#f90,color:#fff

Understanding Workspaces

A VS Code workspace is a collection of one or more folders with associated configuration. There are two types:

Single-Folder Workspace

The .vscode folder in your project root contains settings.json, launch.json, tasks.json, and extensions.json. These are automatically loaded when you open the folder.

Multi-Root Workspace

A .code-workspace file defines multiple folders with their own settings:

{
  "folders": [
    {
      "name": "API",
      "path": "api]
    },
    {
      "name": "Frontend",
      "path": "frontend"
    },
    {
      "name": "Shared Types",
      "path": "../packages/shared"
    }
  ],
  "settings": {
    "editor.fontSize": 14,
    "editor.tabSize": 2,
    "files.exclude": {
      "**/node_modules": true
    }
  },
  "extensions": {
    "recommendations": [
      "dbaeumer.vscode-eslint",
      "esbenp.prettier-vscode",
      "eamodio.gitlens]
    ]
  },
  "launch": {
    "configurations": [
      {
        "name": "API Server",
        "type": "node",
        "request": "launch",
        "program": "${workspaceFolder}/api/src/server.js]
      },
      {
        "name": "Frontend Dev",
        "type": "node",
        "request": "launch",
        "runtimeExecutable": "npm",
        "runtimeArgs": ["run", "dev"],
        "cwd": "${workspaceFolder}/frontend"
      }
    ],
    "compounds": [
      {
        "name": "Full Stack",
        "configurations": ["API Server", "Frontend Dev"]
      }
    ]
  }
}

When you open this workspace file, VS Code loads all three folders, applies the shared settings, recommends the listed extensions, and makes the compound launch configuration available.

VS Code Profiles

Profiles let you create independent sets of extensions, settings, keybindings, and UI state.

Creating a Profile

# Open the Command Palette (Ctrl+Shift+P) and run:
# "Profiles: Create Profile"

# Or use the gear icon in the bottom-left corner:
# Manage → Profiles → Create Profile

Name your profile and select a base profile (None, Default, or an existing one). VS Code copies the current settings into the new profile.

Profile Configuration Files

Profiles are stored in:

• Linux: ~/.config/Code/User/profiles/
• macOS: ~/Library/Application Support/Code/User/profiles/
• Windows: %APPDATA%\Code\User\profiles\

Each profile has its own extensions.json, settings.json, keybindings.json, and tasks.json.

Switching Profiles

# Command Palette → "Profiles: Switch Profile"
# Or click the profile badge in the bottom-left corner

You can assign a keyboard shortcut:

// keybindings.json — profiles section
{
  "key": "ctrl+alt+1",
  "command": "workbench.action.switchProfile",
  "args": { "profileName": "Python Dev" }
}

Profile Example: Python Developer

// settings.json for Python profile
{
  "python.analysis.typeCheckingMode": "basic",
  "python.formatting.provider": "black",
  "[python]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "ms-python.black-formatter"
  },
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false,
  "files.associations": {
    "*.py": "python"
  }
}

Extensions for this profile: Python, Pylance, Black Formatter, Python Test Explorer, Django, Jinja.

Profile Example: Frontend Developer

// settings.json for Frontend profile
{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "emmet.includeLanguages": {
    "javascript": "javascriptreact",
    "typescript": "typescriptreact"
  },
  "css.lint.unknownAtRules": "ignore",
  "files.associations": {
    "*.jsx": "javascriptreact",
    "*.tsx": "typescriptreact"
  }
}

Extensions for this profile: ESLint, Prettier, npm Intellisense, Path Intellisense, Tailwind CSS IntelliSense, Auto Import.

Profile Switcher with Tasks

Automate profile switching when you open a project:

// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Switch to Frontend Profile",
      "type": "shell",
      "command": "code --profile Frontend .",
      "problemMatcher": [],
      "runOptions": { "runOn": "folderOpen" }
    }
  ]
}

Workspace-Level vs User-Level Settings

Understanding which setting goes where prevents confusion:

Settings cascade: Folder > Workspace > Profile > User. More specific scopes override less specific ones.

Sharing Workspace Config with Teams

Create a .code-workspace file checked into version control:

{
  "folders": [
    { "name": "Application", "path": "." }
  ],
  "settings": {
    "editor.rulers": [80, 100],
    "files.trimTrailingWhitespace": true,
    "files.insertFinalNewline": true
  },
  "extensions": {
    "recommendations": [
      "dbaeumer.vscode-eslint",
      "esbenp.prettier-vscode",
      "eamodio.gitlens",
      "github.vscode-pull-request-github]
    ],
    "unwantedRecommendations": [
      "hookyqr.beautify]
    ]
  }
}

When a team member opens the .code-workspace file, VS Code prompts them to install the recommended extensions. The settings apply automatically.

Exporting and Importing Profiles

# Export a profile to share with your team:
# Command Palette → "Profiles: Export Profile"
# Select what to include (settings, extensions, keybindings)
# VS Code generates a URL or file

# Import a profile:
# Command Palette → "Profiles: Import Profile"
# Paste the URL or select the file

Exported profiles include only the diff from the Default profile, making them portable and small.

Common Mistakes

1. Confusing User and Workspace Settings

Putting team-wide settings in User settings means each developer must configure them manually. Always use Workspace settings for project-level configuration.

2. Not Using Profiles for Different Roles

Running Python and frontend extensions simultaneously slows VS Code. Create separate profiles for each role and switch as needed.

3. Forgetting to Share extensions.json

Workspace settings only cover settings. Add extensions.json with recommendations so new team members get prompted to install the right extensions.

4. Hardcoding Absolute Paths in Workspace Files

Use ${workspaceFolder} relative paths in .code-workspace. Absolute paths like /home/user/project/api break on other machines.

5. Not Versioning the Workspace File

Keep .code-workspace in version control. Without it, every team member must manually replicate your folder layout and configuration.

6. Too Many Workspace Folders

A multi-root workspace with 15+ folders slows the editor. Group related folders into a single root and use separate workspace files for unrelated projects.

7. Profile Bloat

Profiles accumulate unused extensions over time. Audit each profile quarterly: disable extensions you haven't used in a month.

Practice Questions

1. What is the difference between a single-folder workspace and a multi-root workspace? A single-folder workspace uses the .vscode/ directory in the project root. A multi-root workspace uses a .code-workspace file that can reference multiple folders, each with its own settings.

2. How do you recommend extensions to your team via a workspace? Add an extensions.recommendations array in the workspace settings or create .vscode/extensions.json with the recommendations field. VS Code prompts team members to install them.

3. What scope overrides what in VS Code settings? Folder settings override Workspace settings, which override Profile settings, which override User settings. More specific scopes always win.

4. How do you export a profile to share with a colleague? Use Command Palette → "Profiles: Export Profile". Select what to include and VS Code generates a shareable URL or file.

5. Challenge: Your team works on a monorepo with a Node.js API, a React frontend, shared TypeScript types, and a Python data pipeline. Design a workspace configuration that gives each developer the right tools for their role. Answer: Create a .code-workspace file with four folders. Add separate VS Code profiles for Node.js dev, React dev, and Python dev. Include a task that auto-switches profiles based on which folder the developer opens first. Share the workspace file in the repo root.

FAQ

What's Next

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro. Updated 2026-06-23.