cursor-upgrade-migration

Cursor Upgrade & Migration

Upgrade Cursor IDE versions, migrate from VS Code, and transfer configurations between machines.

Version Upgrades

Auto-Update (Recommended)

Cursor checks for updates automatically. When available:

1. A notification appears: "A new version is available"
2. Click "Restart to Update" or go to Help > Check for Updates
3. Cursor downloads, installs, and restarts

Manual Update

If auto-update fails or is disabled:

# macOS (Homebrew)
brew upgrade --cask cursor

# macOS/Linux/Windows: Download latest from
# https://cursor.com/download

# Linux AppImage: replace the old file
curl -fSL https://download.cursor.com/linux/appImage/x64 -o cursor.AppImage
chmod +x cursor.AppImage

Pre-Upgrade Checklist

[ ] Note current version: Help > About
[ ] Check release notes: changelog.cursor.sh
[ ] Backup settings:
    macOS: cp -r ~/Library/Application\ Support/Cursor/User ~/cursor-settings-backup
    Linux: cp -r ~/.config/Cursor/User ~/cursor-settings-backup
[ ] Export extension list:
    cursor --list-extensions > extensions-backup.txt
[ ] Commit any unsaved work to git
[ ] Note any custom keybindings (keybindings.json)

Post-Upgrade Verification

[ ] Cursor launches without errors
[ ] Sign-in still active (check top-right user icon)
[ ] AI features work: try Cmd+L, type a question
[ ] Tab completion works: type code, see ghost text
[ ] Extensions loaded: Cmd+Shift+X, verify list
[ ] Custom keybindings preserved: test your shortcuts
[ ] Project rules still load: @Cursor Rules in chat
[ ] Indexing status: check status bar

VS Code to Cursor Migration

Automatic Import (First Launch)

On first launch, Cursor detects VS Code and offers one-click import:

What migrates:
  ✅ settings.json (editor preferences)
  ✅ keybindings.json (custom shortcuts)
  ✅ User snippets
  ✅ Color themes
  ✅ Compatible extensions (from Open VSX Registry)

What does NOT migrate:
  ❌ Microsoft-exclusive extensions (Copilot, Live Share, Remote-SSH)
  ❌ Extension login states / databases
  ❌ Workspace trust settings
  ❌ Task configurations (.vscode/tasks.json -- copies but may need adjustment)

Manual Migration

If you skipped the auto-import:

# Copy settings (macOS example)
cp ~/Library/Application\ Support/Code/User/settings.json \
   ~/Library/Application\ Support/Cursor/User/settings.json

# Copy keybindings
cp ~/Library/Application\ Support/Code/User/keybindings.json \
   ~/Library/Application\ Support/Cursor/User/keybindings.json

# Copy snippets
cp -r ~/Library/Application\ Support/Code/User/snippets/ \
      ~/Library/Application\ Support/Cursor/User/snippets/

# Reinstall extensions (from backup list)
while read ext; do cursor --install-extension "$ext"; done < extensions-backup.txt

Extension Marketplace Differences

Cursor uses Open VSX Registry instead of Microsoft's VS Code Marketplace:

For unavailable extensions, download .vsix from the VS Code Marketplace website and install manually: Cmd+Shift+P > Extensions: Install from VSIX...

Running VS Code and Cursor Side-by-Side

Both can be installed simultaneously. They use separate:

• Settings directories
• Extension directories
• Configuration files

You can open the same project in both editors at once (though be careful with file save conflicts).

Migration Between Machines

Export Configuration

# List all extensions
cursor --list-extensions > cursor-extensions.txt

# Copy settings files
cp ~/Library/Application\ Support/Cursor/User/settings.json .
cp ~/Library/Application\ Support/Cursor/User/keybindings.json .

# Copy project rules (these are already in git if committed)
# .cursor/rules/*.mdc are project-level, not machine-level

Import on New Machine

# Install Cursor
# Sign in (settings sync if available)

# Restore settings
cp settings.json ~/Library/Application\ Support/Cursor/User/
cp keybindings.json ~/Library/Application\ Support/Cursor/User/

# Install extensions
while read ext; do cursor --install-extension "$ext"; done < cursor-extensions.txt

Settings to Review After Machine Transfer

// settings.json -- platform-specific settings to check
{
  "terminal.integrated.defaultProfile.osx": "zsh",    // macOS
  "terminal.integrated.defaultProfile.linux": "bash",  // Linux
  "editor.fontFamily": "Fira Code",                    // Font must be installed
  "files.watcherExclude": { ... }                      // Paths may differ
}

Handling Breaking Changes

.cursorrules to .cursor/rules/ Migration

If upgrading from a Cursor version that used .cursorrules:

1. Create .cursor/rules/ directory
2. Split .cursorrules content into scoped .mdc files:
   • Global rules → project.mdc with alwaysApply: true
   • Language rules → typescript.mdc with globs: "**/*.ts"
3. Test: open Chat, type @Cursor Rules to verify rules load
4. Delete .cursorrules after confirming

Cursor 2.0 Changes

Cursor 2.0 introduced:

• Agent-first architecture (Composer defaults to Agent mode)
• New Composer model (faster generation)
• Parallel agents (up to 8 simultaneous)
• Bug fixes in Chat may appear as: settings key renames, deprecated fields

Check changelog.cursor.sh for specific breaking changes.

Enterprise Considerations

• Managed deployment: Use MDM (macOS) or SCCM (Windows) to distribute Cursor with pre-configured settings
• Version pinning: Enterprise admins can control which Cursor versions are deployed
• Settings templates: Create a starter settings.json for new team members
• Rollback: Keep the previous installer if an update causes issues; downgrade by reinstalling

Resources

• Cursor Changelog
• Cursor Downloads
• VS Code Migration Guide
• Extensions Documentation