Introduction

When code . does not work on macOS, it almost always means the VS Code shell command is not installed in your system PATH. The fix takes 10 seconds: open VS Code, press Cmd+Shift+P, type "Shell Command: Install 'code' command in PATH", and run it. If that does not resolve the issue, the problem is usually a shell configuration or permissions conflict that requires a manual PATH update.

What the code Command Actually Does

The code command is a shell script that launches the VS Code Electron app and passes arguments to it. When you run code ., it tells VS Code to open the current directory as a workspace. When you run code myfile.py, it opens that specific file.

This shell script lives at a path like /usr/local/bin/code (Intel Macs) or the VS Code application bundle. The "Install 'code' command in PATH" action creates a symbolic link from /usr/local/bin/code to the actual script inside the VS Code .app bundle:

/usr/local/bin/code -> /Applications/Visual Studio Code.app/Contents/Resources/app/bin/code

If this symlink is missing or broken, the terminal cannot find the code command.

Fix 1: Install the Shell Command from VS Code

This is the official and most reliable method:

1. Open Visual Studio Code (from Spotlight, Dock, or Applications folder).
2. Press Cmd+Shift+P to open the Command Palette.
3. Type Shell Command: Install 'code' command in PATH.
4. Click the result and enter your password if prompted.
5. Open a new terminal window (existing windows will not pick up the change).
6. Run code . in any directory.

# Verify the command is now available
which code
# Expected output: /usr/local/bin/code

Fix 2: Add VS Code to PATH Manually

If the Command Palette method fails due to permissions or a non-standard installation path, add the VS Code binary directory to your PATH manually.

For zsh (default shell on macOS Catalina and later):

1# Add this line to ~/.zshrc
2cat >> ~/.zshrc << 'EOF'
3export PATH="$PATH:/Applications/Visual Studio Code.app/Contents/Resources/app/bin"
4EOF
5
6# Reload the shell configuration
7source ~/.zshrc
8
9# Verify
10which code
11code --version

For bash (default on older macOS versions):

1# Add this line to ~/.bash_profile
2cat >> ~/.bash_profile << 'EOF'
3export PATH="$PATH:/Applications/Visual Studio Code.app/Contents/Resources/app/bin"
4EOF
5
6source ~/.bash_profile
7which code

If you installed VS Code somewhere other than /Applications, adjust the path accordingly.

Fix 3: Recreate the Symlink Manually

Sometimes the symlink at /usr/local/bin/code exists but points to a stale location (for example, after moving VS Code between directories or upgrading). Remove it and recreate:

1# Remove the old symlink
2sudo rm /usr/local/bin/code
3
4# Create a fresh symlink
5sudo ln -s "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code" /usr/local/bin/code
6
7# Verify
8code --version

Fix 4: Resolve Permission Issues

On macOS, /usr/local/bin may not exist or may have restricted permissions, especially on a fresh system. Create it and set proper ownership:

1# Create the directory if it does not exist
2sudo mkdir -p /usr/local/bin
3
4# Set ownership to your user
5sudo chown -R $(whoami) /usr/local/bin
6
7# Now install the shell command from VS Code's Command Palette

If macOS System Integrity Protection (SIP) is preventing writes to /usr/local/bin, the manual PATH approach (Fix 2) is the better alternative since it does not require writing to protected directories.

Fix 5: VS Code Insiders or Multiple Installations

If you use VS Code Insiders instead of the stable release, the command is code-insiders, not code:

code-insiders .

To install the Insiders shell command, open VS Code Insiders and use the same Command Palette method. The symlink will be created as /usr/local/bin/code-insiders.

If you have both stable and Insiders installed and want code to always point to one of them, set an alias:

# In ~/.zshrc
alias code="/Applications/Visual\ Studio\ Code.app/Contents/Resources/app/bin/code"

Diagnosing the Problem

When none of the fixes work, run these diagnostic commands to understand the state of your system:

1# Check if the command exists anywhere in PATH
2which code
3type code
4
5# Check what your PATH contains
6echo $PATH | tr ':' '\n' | grep -i code
7
8# Check if the symlink exists and where it points
9ls -la /usr/local/bin/code
10
11# Check if VS Code is installed in the expected location
12ls "/Applications/Visual Studio Code.app"
13
14# Check your current shell
15echo $SHELL
16
17# Check which config file your shell sources
18# zsh: ~/.zshrc, ~/.zprofile
19# bash: ~/.bash_profile, ~/.bashrc

Homebrew Users

If you installed VS Code via Homebrew Cask, the code command should be set up automatically. If it is not, reinstall:

brew reinstall --cask visual-studio-code

Homebrew creates the symlink during installation. If it was removed, reinstalling recreates it.

Common Pitfalls

Not opening a new terminal after installing the shell command. The PATH change only takes effect in new shell sessions. Existing terminal tabs or windows still use the old PATH. Always open a fresh terminal window after running the install command.

Editing the wrong shell config file. macOS Catalina and later default to zsh, but some developers have switched back to bash or use fish. Run echo $SHELL to confirm which shell you are using, then edit the corresponding config file.

Having a stale alias or function named code. If an alias or shell function named code was defined in your shell config, it takes precedence over the binary in PATH. Run type code to check. If it shows an alias, remove it from your rc file.

Installing the command for one user but running as another. The /usr/local/bin symlink is system-wide, but PATH modifications in ~/.zshrc only affect the user whose home directory contains that file. This matters on shared machines or when using sudo.

Moving VS Code after installing the shell command. Dragging VS Code from ~/Downloads to /Applications after running the shell command install breaks the symlink. Reinstall the shell command after moving the app.

Summary

The code . command not working on macOS is almost always a PATH issue. The fastest fix is using VS Code's built-in Command Palette to install the shell command (Cmd+Shift+P, then "Shell Command: Install 'code' command in PATH"). For cases where that fails, manually adding the VS Code binary directory to your shell's PATH in ~/.zshrc or ~/.bash_profile is a reliable alternative. After any fix, always open a new terminal window to pick up the changes.