Cursor AI Code Editor Complete Installation Guide: VS Code Migration, AI Model Selection & .cursorrules Setup
Cursor AI Code Editor: The Complete Installation & Configuration Guide
Cursor is an AI-native code editor built on top of VS Code that supercharges your development workflow with intelligent code completion, multi-file editing, and natural language commands. This guide walks you through installation, VS Code settings migration, AI model configuration, and project-level customization with .cursorrules.
Step 1: Download and Install Cursor
- Visit cursor.com and click Download for your operating system (Windows, macOS, or Linux).- Run the installer:
Windows:Double-click the.exefile and follow the setup wizard.macOS:Open the.dmgfile and drag Cursor to your Applications folder.Linux:Install the AppImage:chmod +x cursor-.AppImage ./cursor-.AppImage- Launch Cursor. On first run you will be prompted to sign in or create an account.
Step 2: Migrate Your VS Code Settings
Cursor provides a built-in one-click migration tool that imports extensions, keybindings, settings, and snippets from VS Code.
- Open Cursor and navigate to **File → Preferences → VS Code Import** (or use the Command Palette).- Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS) and type:Cursor: Import VS Code Settings- Select the items you want to import:
settings.json)- Keybindings (keybindings.json)- SnippetsIf you prefer manual migration, copy your VS Code configuration files directly:
# macOS / Linux
cp -r ~/.vscode/extensions ~/.cursor/extensions
cp ~/Library/Application\ Support/Code/User/settings.json ~/.cursor/User/settings.json
Windows (PowerShell)
Copy-Item -Recurse “$env:USERPROFILE.vscode\extensions” “$env:USERPROFILE.cursor\extensions”
Copy-Item “$env:APPDATA\Code\User\settings.json” “$env:APPDATA\Cursor\User\settings.json”
Step 3: Configure AI Model Selection
Cursor supports multiple AI models. You can switch models based on your task complexity and speed requirements.
- Open **Settings → Cursor → Models** or press Ctrl+Shift+P and type Cursor: Model Settings.- Choose your preferred model for each feature:
| Feature | Recommended Model | Use Case |
|---|---|---|
| Tab Completion | cursor-small | Fast inline suggestions |
| Chat (Cmd+L) | claude-sonnet-4-20250514 | General coding questions |
| Composer (Cmd+I) | claude-sonnet-4-20250514 | Multi-file edits |
| Complex Refactors | claude-opus-4-20250514 | Large-scale architecture changes |
| Agent Mode | claude-sonnet-4-20250514 | Autonomous multi-step tasks |
OpenAI API Key: YOUR_API_KEY
Anthropic API Key: YOUR_API_KEY
Google AI API Key: YOUR_API_KEY
## Step 4: Set Up .cursorrules for Project-Level Configuration
The .cursorrules file lives in your project root and provides context-specific instructions that guide Cursor’s AI behavior for that project.
- Create the file in your project root:touch .cursorrules- Add project-specific rules. Here is a practical example for a Next.js TypeScript project:
# .cursorrules
You are an expert in TypeScript, Next.js 14 App Router, React, and Tailwind CSS.
Code Style
- Use functional components with TypeScript interfaces
- Prefer named exports over default exports
- Use path aliases (@/components, @/lib, @/types)
- Follow the existing project structure in /src
Conventions
- Use server components by default; add “use client” only when needed
- Handle errors with proper try/catch and error boundaries
- Write unit tests with Vitest for all utility functions
- Use Zod for runtime validation of API inputs
Project Context
- Database: PostgreSQL with Prisma ORM
- Auth: NextAuth.js v5
- State: Zustand for client state
- API: tRPC for type-safe endpoints
Restrictions
- Never use any as a type
- Never use inline styles; use Tailwind classes
Do not install new dependencies without asking first
For larger projects, you can also use the .cursor/rules directory with multiple rule files:
mkdir -p .cursor/rules
Create modular rule files
echo ‘Always use ES modules and async/await’ > .cursor/rules/javascript.md
echo ‘Follow REST conventions for API routes’ > .cursor/rules/api.md
echo ‘Write tests alongside source files as *.test.ts’ > .cursor/rules/testing.md
Step 5: Essential Keyboard Shortcuts & Workflow
| Action | Windows/Linux | macOS |
|---|---|---|
| AI Chat Panel | Ctrl+L | Cmd+L |
| Inline Edit (Composer) | Ctrl+I | Cmd+I |
| Accept Suggestion | Tab | Tab |
| Reject Suggestion | Escape | Escape |
| Toggle Agent Mode | Ctrl+. | Cmd+. |
| Reference File in Chat | @filename | @filename |
| Reference Docs | @docs | @docs |
@filename.ts, documentation with @docs, or codebase-wide context with @codebase to give the AI precise context.- **Leverage Agent Mode:** For complex multi-step tasks (scaffolding features, refactoring across files), switch to Agent mode which can run terminal commands, create files, and iterate autonomously.- **Pin context files:** In the Chat panel, pin frequently referenced files so they persist across conversations without re-adding them.- **Use .cursorignore:** Create a .cursorignore file (same syntax as .gitignore) to exclude large generated files, node_modules, or sensitive files from AI indexing:# .cursorignore
node_modules/
dist/
.env
*.min.js
package-lock.json.cursorrules to version control so your entire team benefits from consistent AI behavior across the project.
## Troubleshooting Common Issues
| Problem | Cause | Solution |
|---|---|---|
| Extensions not working after migration | Incompatible extension versions | Open the Extensions panel, disable broken extensions, and reinstall them from the marketplace |
| AI responses are slow or timing out | Network issues or model overload | Switch to a faster model (e.g., cursor-small for completions), check your internet connection, or try again during off-peak hours |
| API key not recognized | Incorrect key format or expired key | Re-enter the key in Settings → Models → API Keys; ensure no leading/trailing whitespace |
| .cursorrules not being applied | File not in project root | Ensure the file is named exactly .cursorrules (no extension) and placed in the workspace root directory |
| High memory usage | Large project indexing | Add large directories to .cursorignore and restart Cursor |
Can I use Cursor alongside VS Code without conflicts?
Yes. Cursor and VS Code are completely independent applications. They use separate configuration directories, so you can run both simultaneously without any conflicts. Your VS Code installation remains untouched after migrating settings to Cursor.
Is Cursor free to use, and what does the Pro plan include?
Cursor offers a free Hobby tier that includes 2,000 code completions and 50 premium model requests per month. The Pro plan (currently $20/month) provides unlimited completions, 500 fast premium requests per month, and access to the latest models including Claude and GPT-4. The Business plan adds team management, centralized billing, and admin controls.
How do I update .cursorrules without restarting Cursor?
Cursor automatically detects changes to .cursorrules when you save the file. There is no need to restart the editor. Simply edit and save the file, and your next AI interaction will use the updated rules. You can verify by asking the AI to describe its current instructions in the Chat panel.