Installing Visual Studio Code on Ubuntu: Engineer's Runbook

Teams migrating to Ubuntu commonly standardize on VS Code—lightweight, cross-platform, fast to bootstrap a new dev environment. The "standard" install path: integrate the official Microsoft APT repository for streamlined updates via system package management.

Note: This guide covers Ubuntu 22.04 LTS (jammy) and 20.04 LTS (focal). Non-LTS releases may require modified repositories.

Install Steps: Official Repository (Recommended)

Here's the minimal-privilege approach.

1. Ensure prerequisites. Microsoft’s repository uses GPG keys and direct HTTPS pulls.

sudo apt update
sudo apt install -y wget gpg apt-transport-https

2. Import the Microsoft GPG key and persist to /usr/share/keyrings/ (not trusted.gpg—prevents unintentional trust creep):

wget -qO- https://packages.microsoft.com/keys/microsoft.asc | \
  gpg --dearmor | sudo tee /usr/share/keyrings/packages.microsoft.gpg >/dev/null

3. Add the VS Code repository. Target /etc/apt/sources.list.d/vscode.list explicitly:

echo "deb [arch=amd64 signed-by=/usr/share/keyrings/packages.microsoft.gpg] \
https://packages.microsoft.com/repos/code stable main" | \
sudo tee /etc/apt/sources.list.d/vscode.list

4. Refresh APT metadata:

sudo apt update

5. Install Visual Studio Code:

sudo apt install -y code

Result: /usr/bin/code is symlinked to /usr/share/code/bin/code. The package is now managed by APT; standard admin tasks (upgrade, uninstall) work natively.

First Run

Launch with:

code

Or, via launcher. If you see "Failed to load module "canberra-gtk-module" log noise, ignore—it does not affect core functionality. (Can suppress by installing the missing GTK module: sudo apt install libcanberra-gtk-module.)

Practical Workflow Tips

• Project bootstrapping: Quickly open a folder.

  cd ~/workspace/myservice
  code .
  

• Essential extensions:

  code --install-extension ms-python.python
  code --install-extension ms-vscode.cpptools
  code --install-extension eamodio.gitlens
  

  Note: Extension install via CLI fails silently if the code process is running with the same user. Either close Code, or append --force (may lose unsaved workspace state).

Snap Alternative (Trade-offs)

For ultra-fast installs on ephemeral VMs:

sudo snap install --classic code

Trade-offs: Snap's confinement limits access to system directories and can break some extensions (Python interpreter discovery, Docker integration). Updates are auto-managed, but lag several days behind the primary apt repo. In enterprise settings, prefer the APT method for auditability and fewer surprises.

Gotchas & Troubleshooting

• Update friction: If apt reports hash sum mismatch after adding the repository, run sudo apt clean and retry.
• Key management: Microsoft occasionally rotates signing keys. Trace errors containing NO_PUBKEY—force-refresh step 2 if encountered.
• Multiple DEs: Under Wayland, you may experience clipboard oddities; fallback to X11 (code --force-device-scale-factor=1) if necessary.

Why Not Direct .deb?

Manual .deb install works, but doesn't handle auto-updates. You risk running an out-of-date editor missing security patches.

Summary Table

The APT-integrated approach remains optimal for maintainability. For airgapped or legacy environments: capture the .deb and dependencies with apt download and dpkg -i.

Non-obvious tip: You can define VS Code settings and extension lists in a portable config (see %APPDATA%/Code/User/settings.json or ~/.config/Code/User/settings.json). For fast onboarding, script initial workspace setup on fresh Ubuntu boxes with a single bash block.

Guide validated on Ubuntu 22.04.4 LTS (kernel 5.15.x), VS Code 1.89.x. Minor differences may occur on older releases or custom remixes.