Introduction

To change indentation in VS Code, click the indentation indicator in the bottom-right status bar (it shows something like Spaces: 4 or Tab Size: 2). From there you can switch between tabs and spaces, change the tab width, or convert the existing file's indentation. For project-wide defaults, set editor.tabSize and editor.insertSpaces in your settings.json.

Changing indentation involves three separate concerns: choosing tabs vs. spaces, choosing the column width, and converting existing files. VS Code handles all three, but they are controlled in different places.

Change Indentation for the Current File

The fastest method is the status bar. Look at the bottom-right corner of the VS Code window. You will see an indicator like Spaces: 4.

Click it to open a menu with these options:

• Indent Using Spaces: Switch to spaces and choose a width.
• Indent Using Tabs: Switch to tab characters and choose a display width.
• Convert Indentation to Spaces: Rewrite existing tabs to spaces in the current file.
• Convert Indentation to Tabs: Rewrite existing spaces to tabs in the current file.

You can also open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and type "indentation" to find these same commands.

1> Convert Indentation to Spaces
2> Convert Indentation to Tabs
3> Indent Using Spaces
4> Indent Using Tabs
5> Change Tab Display Size

The key distinction: "Indent Using" changes how new indentation is inserted. "Convert Indentation" rewrites the current file's existing whitespace.

Set Default Indentation in Settings

To configure the default for all new files, add these to your settings.json:

1{
2  "editor.insertSpaces": true,
3  "editor.tabSize": 4,
4  "editor.detectIndentation": false
5}

When editor.detectIndentation is true (the default), VS Code reads the current file and overrides your tabSize and insertSpaces settings to match whatever the file already uses. This is helpful for mixed-style repositories but confusing when you expect your settings to always apply. Set it to false if you want your settings to take precedence.

Language-Specific Settings

Different languages have different conventions. Python uses 4 spaces, many JavaScript style guides use 2 spaces, and Go uses tabs. VS Code supports per-language overrides:

1{
2  "[python]": {
3    "editor.tabSize": 4,
4    "editor.insertSpaces": true
5  },
6  "[javascript]": {
7    "editor.tabSize": 2,
8    "editor.insertSpaces": true
9  },
10  "[go]": {
11    "editor.insertSpaces": false,
12    "editor.tabSize": 4
13  },
14  "[makefile]": {
15    "editor.insertSpaces": false
16  }
17}

Language-specific settings override global settings but are themselves overridden by .editorconfig and formatter extensions.

EditorConfig Integration

Many projects include an .editorconfig file to enforce consistent formatting across different editors and developers. VS Code respects .editorconfig automatically (with the built-in support or the EditorConfig extension).

1root = true
2
3[*]
4indent_style = space
5indent_size = 4
6end_of_line = lf
7charset = utf-8
8trim_trailing_whitespace = true
9
10[*.js]
11indent_size = 2
12
13[*.go]
14indent_style = tab
15
16[Makefile]
17indent_style = tab

When .editorconfig is present, it takes priority over VS Code's settings.json. This is intentional: project rules should override personal preferences on team codebases.

Formatters Override Everything

If you use a formatter like Prettier, ESLint, Black, or gofmt, that formatter has the final word on indentation when you save or format the file.

For example, with Prettier configured for 2-space indentation:

1{
2  "tabWidth": 2,
3  "useTabs": false
4}

No matter what your VS Code settings say, Prettier will rewrite the file to 2 spaces on format. The priority chain is:

1Formatter (Prettier, Black, etc.)
2  > .editorconfig
3    > Language-specific VS Code settings
4      > Global VS Code settings
5        > Auto-detected indentation (if detectIndentation is true)

Understanding this hierarchy is essential. Most "my indentation keeps changing back" issues are caused by a formatter or .editorconfig that the developer forgot about.

Workspace vs. User Settings

VS Code has two levels of settings:

• User Settings: Apply globally to all projects. Located at ~/.config/Code/User/settings.json (Linux), ~/Library/Application Support/Code/User/settings.json (macOS), or %APPDATA%\Code\User\settings.json (Windows).
• Workspace Settings: Apply only to the current project. Located at .vscode/settings.json in the project root.

1// .vscode/settings.json (workspace-level)
2{
3  "editor.tabSize": 2,
4  "editor.insertSpaces": true
5}

Workspace settings override user settings. Commit .vscode/settings.json to the repository so all team members use the same indentation without configuring their personal settings.

Keyboard Shortcuts for Indentation

To manually indent or outdent selected lines:

For reindenting an entire file after changing settings:

1. Select all (Ctrl+A / Cmd+A).
2. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
3. Run Format Document (if a formatter is installed) or Reindent Lines.

Batch Converting Multiple Files

If you need to convert indentation across an entire project (for example, migrating from tabs to 2-space indentation), a command-line tool is faster than doing it file by file in VS Code.

Using expand (Unix):

# Convert tabs to 2 spaces in all JavaScript files
find ./src -name "*.js" -exec sh -c 'expand -t 2 "$1" > "$1.tmp" && mv "$1.tmp" "$1"' _ {} \;

Using Prettier:

npx prettier --write --tab-width 2 --use-tabs false "src/**/*.js"

Common Pitfalls

Changing editor.tabSize and expecting existing tabs in the file to become spaces is the most common mistake. Changing the tab size only changes how tab characters are displayed, not the actual file content. You must explicitly run "Convert Indentation to Spaces" to rewrite the file.

Fighting a formatter or .editorconfig without checking whether the project deliberately enforces indentation standards leads to frustration. Check for .editorconfig, .prettierrc, pyproject.toml, or similar config files before overriding indentation settings.

Leaving editor.detectIndentation enabled and then wondering why a file ignores your defaults is another frequent issue. VS Code detects the file's current style and follows it, which silently overrides your chosen settings.

Committing files with mixed tabs and spaces happens when some team members use different settings. An .editorconfig file or a pre-commit formatting hook prevents this.

Summary

• Click the status bar indicator to change indentation for the current file.
• Set editor.insertSpaces and editor.tabSize in settings.json for defaults.
• Use "Convert Indentation to Spaces/Tabs" from the Command Palette to rewrite existing files.
• Use language-specific settings for projects that span multiple languages.
• Check for .editorconfig and formatter configs before troubleshooting unexpected indentation behavior.
• Commit .vscode/settings.json to align the team on indentation standards.