VS Code: quickstart

This quickstart takes you from "I just installed VS Code" to "I can edit locally, run remotely, and ship a change" without detours. It assumes you have never set VS Code up for data work before. No prior knowledge of Dev Containers, launch configs, or MCP servers is assumed.

By the end you will have:

• VS Code installed with the paved-path extension pack.
• A Python interpreter selected and a virtual env hooked up.
• A Databricks workspace connected, a cluster attached, and "Hello world" running remotely via Databricks Connect.
• A dbt project parsing cleanly with live CTE previews.
• Git sign-in and PR review working inside the editor.

1. Install VS Code

Download VS Code from code.visualstudio.com. The stable channel is fine. The Insiders build ships faster but is not required.

Open VS Code. When it asks "Do you trust the authors of the files in this folder?", answer yes for repos you own. Answer no for repos you are just inspecting; restricted mode disables extensions that could execute arbitrary code.

2. Sign in and turn on Settings Sync

Click the account icon in the lower-left corner. Sign in with GitHub. Turn on Settings Sync:

1. Click Backup and Sync Settings from the account menu.
2. Accept all categories: settings, keybindings, extensions, snippets, UI state.
3. Choose GitHub as the backing store.

From now on every machine you sign in to pulls the same configuration. A laptop swap takes minutes, not days.

3. Install the extension pack

Open the Extensions view (Cmd+Shift+X on macOS, Ctrl+Shift+X on Linux and Windows). Install these in order:

Python and SQL:

• ms-python.python
• ms-python.vscode-pylance
• charliermarsh.ruff
• dbtLabsInc.dbt (if you are on dbt Fusion)
• innoverio.vscode-dbt-power-user (if you are on dbt Core)
• dorzey.vscode-sqlfluff
• samuelcolvin.jinjahtml

Platforms:

• databricks.databricks

Config and docs:

• redhat.vscode-yaml
• tamasfe.even-better-toml
• mikestead.dotenv
• yzhang.markdown-all-in-one
• bierner.markdown-mermaid

Git:

• eamodio.gitlens
• GitHub.vscode-pull-request-github

Reproducible environments:

• ms-vscode-remote.remote-containers

4. Open a project and select a Python interpreter

Clone a data-product repo and open it:

git clone https://github.com/your-org/churn-analytics
cd churn-analytics
code .

Create a virtual environment with uv:

uv sync

In VS Code, press Cmd+Shift+P and run Python: Select Interpreter. Pick the .venv/bin/python that uv sync created. VS Code writes this selection to .vscode/settings.json so the choice sticks for every contributor.

5. Configure format-on-save

Open the workspace settings file at .vscode/settings.json. If it does not exist, create it. Paste:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit",
    "source.fixAll": "explicit"
  },
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff"
  },
  "[sql]": {
    "editor.defaultFormatter": "dorzey.vscode-sqlfluff"
  },
  "editor.rulers": [100],
  "files.trimTrailingWhitespace": true
}

Save the file. Ruff now formats Python on save and SQLFluff formats SQL on save. The ruler at column 100 is a visual cue, not a hard limit.

6. Connect to Databricks

Open the Databricks extension (the ⚡ icon in the activity bar). Click Configure Databricks Workspace.

1. Paste your workspace URL (e.g., https://dbc-abc123.cloud.databricks.com).
2. Choose OAuth (U2M) as the auth method. Do not use PATs; they rot and leak.
3. Complete the OAuth flow in the browser. VS Code stores the refresh token in your OS keychain.

Once authenticated, pick a compute target:

• A serverless compute for interactive work (recommended).
• An all-purpose cluster on a versioned runtime if serverless is unavailable.

Install the matching Databricks Connect client into your venv:

uv add databricks-connect==<runtime-version>

The runtime version must match the cluster's DBR version (or the serverless compute's advertised version). Mismatches produce cryptic Py4J errors.

7. Run "Hello world" remotely

Create hello.py:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()
df = spark.range(10).toDF("n")
df.show()

In the editor, click Run on Databricks → Debug current file. The file executes locally until it hits spark.range(10), which runs on the remote compute. Output streams back into the integrated terminal.

Set a breakpoint on df.show() and re-run. VS Code pauses there, lets you inspect df in the variables pane, and resumes on continue.

8. Parse your first dbt model

Open a dbt project folder. Install dbt packages:

dbt deps

Run:

dbt parse

If parse succeeds, the dbt extension lights up. Hover over a {{ ref('stg_customers') }} — you should see the resolved model name and path. Click Preview compiled SQL in the model file; the compiled SQL opens in a side panel.

9. Sign in to GitHub and open a PR

Click the account icon, then GitHub: Sign In. Authorize VS Code.

Open the GitHub Pull Requests panel (the octopus-cat icon). You should see open PRs, your assigned reviews, and your own in-flight work.

To open a PR from the branch you are on:

1. Stage and commit from the Source Control view (Cmd+Shift+G).
2. Click Publish Branch.
3. Click Create Pull Request when the panel prompts.

Fill the title as the change will appear in the release log: imperative mood, specific. ("Add churn fact table" beats "Fixed bug.")

10. What to do next

You now have a working editor. The next steps depend on what you build:

• Spark and Databricks work: read edit local, execute remote to understand what the Databricks extension is doing under the hood.
• Reproducible environments for your whole team: read devcontainers and add a .devcontainer/ to your repo.
• Faster inner loop: read the inner loop for per-stack cadence (Python, dbt, Airflow).
• Debugging: read debugging for launch configs and query-profile reading.
• AI agents: read AI agents and MCP servers to wire Claude Code, Copilot, or Cursor into the paved path.
• Keyboard shortcuts: skim commands and shortcuts; the time you spend here pays itself back within a week.

Troubleshooting

code command not found on PATH

Open the command palette, run Shell Command: Install 'code' command in PATH. macOS requires admin approval once.

Extensions do not install (proxy error)

Corporate networks often MITM TLS to VS Code's marketplace. Set http.proxy and http.proxyStrictSSL in user settings. If your org blocks the marketplace entirely, ask platform for the internal VSIX mirror.

Python extension says "No interpreter selected"

Run Python: Select Interpreter from the command palette. If the venv does not appear in the list, enter its path manually or set python.defaultInterpreterPath in .vscode/settings.json.

Databricks extension stuck on "Connecting…"

Kill the extension host (Developer: Reload Window). If the issue persists, check the Databricks Output channel; most likely the OAuth refresh token expired.

See also

• Edit local, execute remote — the pattern behind the Databricks extension.
• The extension ecosystem — why each extension earns its slot.
• Devcontainers — reproducible environments for the whole team.
• Workspace standards — the paved-path rules these defaults implement.