Installation and Platform Setup

You have spent years fine-tuning your VS Code setup — keybindings, extensions, themes, snippets. The last thing you want is to start from scratch in a new editor. The good news: Cursor is a fork of VS Code. Your muscle memory, your extensions, and your settings all transfer in about two minutes. The bad news: installation still has a few platform-specific landmines that can waste an hour if you hit them unprepared.

What You’ll Walk Away With

• Cursor installed and running on your platform with no security warnings or permission issues
• All your VS Code settings, extensions, and keybindings imported automatically
• The cursor shell command working from any terminal
• A verified installation where AI chat responds to prompts and codebase indexing has started

Platform Installation

macOS

Option 1: Homebrew (Recommended)

brew install --cask cursor

This handles code signing and quarantine flags automatically.

Option 2: Direct Download

1. Download from cursor.com/download
2. Open the .dmg file
3. Drag Cursor to Applications

Fixing Security Warnings

If macOS says “Cursor is damaged and can’t be opened”:

xattr -cr /Applications/Cursor.app

If you see “Cursor cannot be opened because the developer cannot be verified”:

1. Open System Settings then Privacy and Security
2. Scroll to “Security” and click Open Anyway
3. Enter your password when prompted

Windows

Option 1: winget (Recommended)

winget install Anysphere.Cursor

Option 2: Direct Installer

1. Download from cursor.com/download
2. Run Cursor-Setup.exe
3. Follow the installer — Cursor installs to %LOCALAPPDATA%\Programs\cursor

Add to PATH

Open Cursor, press Ctrl+Shift+P, and run Install ‘cursor’ command in PATH. Restart your terminal afterward.

Windows Defender

If installation hangs or Cursor is slow on first launch, add an exclusion:

1. Open Windows Security
2. Go to Virus and Threat Protection then Manage Settings
3. Under Exclusions, add the Cursor installation folder

Linux

AppImage Installation

# Download the AppImage
curl -L https://cursor.com/download/linux-x64 -o cursor.AppImage
chmod +x cursor.AppImage

# Install libfuse2 if needed (required for AppImage)
# Ubuntu/Debian:
sudo apt install libfuse2
# Fedora:
sudo dnf install fuse
# Arch:
sudo pacman -S fuse2

# Move to a permanent location
sudo mv cursor.AppImage /opt/cursor.AppImage
sudo ln -s /opt/cursor.AppImage /usr/local/bin/cursor

Create Desktop Entry

cat > ~/.local/share/applications/cursor.desktop << 'EOF'
[Desktop Entry]
Name=Cursor
Exec=/opt/cursor.AppImage --no-sandbox %F
Terminal=false
Type=Application
Icon=cursor
StartupWMClass=Cursor
Categories=Development;IDE;
EOF

GPU Issues

If you see rendering glitches or a blank window:

cursor --disable-gpu

VS Code Migration

Cursor can import everything from VS Code in a single step. This is the fastest path to feeling at home.

1. Open Cursor Settings

   Press Cmd+Shift+J (macOS) or Ctrl+Shift+J (Windows/Linux).

2. Go to General then Account

   Look for the VS Code import section.

3. Click “Import from VS Code”

   Cursor detects and imports:

   • All installed extensions
   • User settings (settings.json)
   • Keyboard shortcuts (keybindings.json)
   • Snippets
   • Theme selections

4. Restart Cursor

   The import takes effect after a restart.

Manual Migration Fallback

If automatic import fails (rare, but it happens with non-standard VS Code installations):

macOS / Linux

# Copy settings
cp ~/.config/Code/User/settings.json ~/.config/Cursor/User/
cp ~/.config/Code/User/keybindings.json ~/.config/Cursor/User/
cp -r ~/.config/Code/User/snippets ~/.config/Cursor/User/

Windows

copy %APPDATA%\Code\User\settings.json %APPDATA%\Cursor\User\
copy %APPDATA%\Code\User\keybindings.json %APPDATA%\Cursor\User\
xcopy %APPDATA%\Code\User\snippets %APPDATA%\Cursor\User\snippets /E /I

Shell Command Setup

Being able to type cursor . in any terminal is essential for the workflows in this guide.

1. Open Cursor
2. Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
3. Type Install ‘cursor’ command in PATH and select it
4. Optionally, also run Install ‘code’ command in PATH for VS Code compatibility
5. Restart your terminal

Verify it works:

cursor --version
cursor .  # Opens current directory in Cursor

Caution

If cursor is not found after installation, the most likely cause is a stale shell session. Close and reopen your terminal. On macOS, you may also need to add /Applications/Cursor.app/Contents/Resources/app/bin to your PATH manually.

Open Your Project and Start Indexing

Open a real project — not an empty folder. Cursor needs files to index.

cd ~/projects/your-real-project
cursor .

When Cursor opens, it immediately begins indexing your codebase. This creates semantic embeddings that the AI uses to find relevant code when you ask questions or request changes.

Monitor Indexing

1. Open Settings: Cmd+Shift+J / Ctrl+Shift+J
2. Navigate to Indexing and Docs
3. Watch the progress bar — small projects finish in under a minute, large monorepos can take 10-15 minutes

Note

You do not need to wait for indexing to finish before continuing this guide. It runs in the background and the AI gets progressively better as more files are indexed.

Verify Your Installation

Run through this quick checklist to make sure everything is working before moving to configuration:

Check	How	Expected Result
Terminal commands	Open terminal with Ctrl+` and type node --version	v18.x or higher
Git integration	Type git status in the terminal	Shows your repo status
AI chat	Press Cmd+I / Ctrl+I and type “Hello”	AI responds in the chat panel
File explorer	Check the sidebar	Your project files are visible
Extensions	Open Extensions panel (Cmd+Shift+X)	Your VS Code extensions appear

Copy-paste prompt to verify AI is working

Open the agent panel with Cmd+I and paste this:

How is this project structured? Give me a brief overview of the main directories and their purpose.

If you get a coherent answer referencing actual files in your project, your installation and indexing are both working.

When This Breaks

“Cursor is damaged” on macOS: Run xattr -cr /Applications/Cursor.app and try again.

Extensions not loading after migration: Clear the extension cache at ~/.config/Cursor/CachedExtensionVSIXs (macOS/Linux) or %APPDATA%\Cursor\CachedExtensionVSIXs (Windows) and restart.

AI chat shows “Rate limit exceeded”: You are on the free tier and have used your daily allocation. Either wait for the reset or upgrade to Cursor Pro.

Indexing stuck at 0%: Check that your project is not entirely in .gitignore patterns. Cursor respects .cursorignore if it exists — make sure you have not accidentally excluded everything.

cursor command not found on Linux: The AppImage does not auto-register shell commands. The symlink in the installation section (ln -s /opt/cursor.AppImage /usr/local/bin/cursor) handles this.

What’s Next

Essential Configuration Enable auto-run, configure privacy settings, and set up Max mode -- the three settings that unlock Cursor's full potential.