How to Install VS Code on macOS: Detailed 2026 Guide

Introduction / Why This Is Needed

Visual Studio Code (VS Code) is a free, powerful, and popular code editor from Microsoft that supports numerous programming languages and has an extensive extension ecosystem. Installing VS Code on macOS is the first step toward creating an efficient development environment. This guide provides a detailed installation process, taking into account macOS specifics, including Macs with Apple Silicon (M1/M2/M3) and Intel processors. Upon completion, you will have a fully functional editor ready for use with Python, JavaScript, Java, and other language projects.

Requirements / Preparation

Before starting the installation, ensure your system meets the following requirements:

• Operating System: macOS 12.0 Monterey or newer (recommended). VS Code also supports macOS 11.0 Big Sur, but for compatibility with new features, it's better to update macOS.
• Processor: Apple Silicon (ARM64) or Intel (x64). It is important to download the correct version for your architecture.
• Free Space: Approximately 500 MB for installation plus additional space for projects and extensions.
• Internet: A stable connection to download the installer (~100 MB) and subsequently load extensions.
• Permissions: Standard macOS user permissions are sufficient for installation in the Applications folder. If installing in a different directory, administrator rights may be required.
• Optional: Homebrew – a package manager for macOS, if you prefer command-line installation.

Step 1: Download the VS Code Installer

1. Open your browser and go to the official Visual Studio Code website: https://code.visualstudio.com/.
2. On the main page, you will see a large blue button Download for macOS. Click it.
3. The system will prompt you to choose an architecture:
   • Apple Silicon (arm64) – for Macs with M1, M2, M3, and newer chips.
   • Intel (x64) – for Macs with Intel processors. If you are unsure, check your Mac's model: click the Apple logo in the top-left corner → About This Mac. The "Processor" line will indicate "Apple M1" or "Intel Core...".
4. The selected file will be named something like VSCode-darwin-arm64.zip or VSCode-darwin-x64.zip and will download to the Downloads folder.

💡 Tip: If you use multiple Macs or want to keep the installer, copy the .zip file to a safe location. It may be useful for offline installation.

Step 2: Install VS Code to the Applications Folder

macOS does not use traditional installers (.exe or .msi); instead, applications are installed by simply copying them to the Applications folder.

1. Open the Downloads folder in Finder.
2. Locate the downloaded .zip file (e.g., VSCode-darwin-arm64.zip).
3. Double-click the .zip file to extract it. macOS will create a Visual Studio Code.app folder (or simply an app with the VS Code icon).
4. Drag the Visual Studio Code.app application to the Applications folder. You can open the Applications folder via Finder (in the sidebar) or through Launchpad.
5. After copying, you can delete the original .zip file to free up space.

⚠️ Important: Do not run VS Code directly from the Downloads folder – always move it to Applications. This ensures the application is properly registered with the system and accessible from Launchpad or Spotlight.

Step 3: First Launch and Basic Setup

Now that VS Code is installed, it needs to be launched and initially configured.

1. Open the Applications folder and double-click Visual Studio Code.
2. On the first launch, macOS may display a warning: "VS Code cannot be opened because it is from an unknown developer". This is a standard Gatekeeper security measure.
   • To bypass this, open System Settings → Privacy & Security.
   • Scroll down to the Security section. You will see a message about VS Code being blocked. Click Open Anyway.
   • Confirm the action in the dialog window. Then try launching VS Code again.
3. VS Code will open and prompt you to accept the License Agreement. Click Accept.
4. A window will appear offering to set up settings synchronization via a Microsoft account. This is useful for syncing settings, extensions, and keybindings across devices. You can skip this step or sign in to your account.
5. After this, you will see the VS Code interface: activity bar on the left, editor, terminal (if open). VS Code is ready for use.

💡 Tip: For quick access, add VS Code to the Dock: launch the app, right-click its icon in the Dock → Options → Keep in Dock.

Step 4: Install Extensions for Your Technology Stack

VS Code becomes truly powerful with extensions. Install those needed for your projects.

1. In VS Code, open Extensions via the icon in the sidebar or the shortcut Cmd+Shift+X.
2. In the search box, type the name of the extension or a topic (e.g., "Python", "Prettier", "GitLens").
3. Click Install for the selected extension.
4. After installation, the extension activates automatically. Some may require a restart of VS Code.

Popular extensions to start with:

• Python – Python language support (from Microsoft).
• ESLint – Linting for JavaScript/TypeScript.
• Prettier – Code formatting.
• GitLens – Enhanced Git capabilities.
• Docker – Container management.
• Material Icon Theme – Icon theme.

Alternative Method: Installation via Homebrew

If you already use Homebrew, VS Code can be installed from the terminal. This is convenient for automation or if you prefer the CLI.

1. Open Terminal from the Applications/Utilities folder or via Spotlight (Cmd+Space, type "Terminal").
2. Run the command:

   brew install --cask visual-studio-code
   

   Homebrew will automatically download and install the latest version of VS Code to the Applications folder.
3. After installation completes, launch VS Code as described in Step 3.
4. To update VS Code via Homebrew, use:

   brew upgrade --cask visual-studio-code
   

💡 Tip: Installing via Homebrew also simplifies removal: brew uninstall --cask visual-studio-code.

Verification

To ensure the installation was successful, perform the following checks:

1. Launch the application: Ensure VS Code opens without errors. The welcome screen should appear.
2. Check version: In the VS Code menu, select Help → About. The window should display the current version (e.g., 1.85.0 or higher) and build information.
3. Create a test file: Create a new file (File → New File or Cmd+N), enter simple code (e.g., print("Hello, VS Code!") for Python), and save it. Ensure syntax highlighting works (e.g., Python keywords are colorized).
4. Terminal functionality: Open the integrated terminal (Terminal → New Terminal or Ctrl+`). Run a simple command, e.g., echo "Terminal works". The terminal should output the text.
5. Extensions: Go to Extensions and verify installed extensions are listed and active (status "Enabled").

If all these steps succeed, VS Code is installed and ready for development.

Possible Issues

Although installing VS Code on macOS usually goes smoothly, some issues may arise. Here are solutions for common cases:

1. Gatekeeper Error: "Cannot be opened because it is from an unknown developer"

• Cause: VS Code is not signed with an Apple certificate, or the system blocks it by default.
• Solution: As described in Step 3, allow launching in System Settings > Privacy & Security → Open Anyway. If the option is not there, ensure you downloaded the file from the official website (not third-party sources). Temporarily disabling Gatekeeper via sudo spctl --master-disable is not recommended due to security risks.

2. VS Code Does Not Launch After Installation

• Cause: Corrupted download archive, extension conflict, or insufficient permissions.
• Solution:
  • Reinstall VS Code: remove the app from the Applications folder (drag to Trash), download again from the official site, and repeat installation.
  • Launch VS Code from the terminal to see errors: open -a "Visual Studio Code". Errors will be printed to the console.
  • Check permissions on the Applications folder: ls -ld /Applications. It should be writable (typically drwxr-xr-x). If not, use sudo chown -R $(whoami) /Applications (caution: this changes the owner of the entire folder).

3. Issues with Extensions on Apple Silicon

• Cause: Some extensions may only be available for x64 architecture and run via Rosetta 2 emulation, which can cause errors or poor performance.
• Solution:
  • Ensure you installed the native Apple Silicon (arm64) version of VS Code. Verify in Help > About – the "ARM64" line should read "true".
  • For extensions, look for versions with ARM64 support. VS Code automatically uses Rosetta 2 for x64 extensions, but native versions are preferable.
  • If an extension does not work, try installing an alternative with similar functionality.

4. Freezing or Slow Performance

• Cause: Too many installed extensions, conflicts between them, or insufficient system resources.
• Solution:
  • Launch VS Code in debug mode: code --disable-extensions from the terminal. If the problem disappears, extensions are the culprit. Disable or remove unnecessary ones via Extensions.
  • Clear the cache: delete the folder ~/Library/Application Support/Code (close VS Code first). Caution: This removes settings and extensions. Make a backup if needed.
  • Increase the memory limit in VS Code settings: add "files.maxMemoryForLargeFilesMB": 4096 to settings.json (via Cmd+, → {} icon in the top-right).

5. Errors When Installing via Homebrew

• Cause: Issues with Homebrew formulas or version conflicts.
• Solution:
  • Update Homebrew: brew update.
  • Check for formula issues: brew doctor.
  • If installation fails, try installing directly from the website as described in the main steps.
  • For a complete reinstall via Homebrew: brew uninstall --cask visual-studio-code && brew install --cask visual-studio-code.