Dec 4, 2025

How to Set Up Windsurf: Complete Installation Guide (2025)

Step-by-step guide to install and configure Windsurf IDE. Learn setup, Cascade AI mode, keyboard shortcuts, and optimization tips for 2025.

Windsurf IDE launched quietly in late 2024 and immediately caught my attention. It’s Codeium’s answer to Cursor AI, and after using it for two months, I’m genuinely impressed.

The setup process is straightforward if you’ve used VS Code before—Windsurf is a fork of VS Code, just like Cursor. But there are some gotchas, especially around Cascade mode (Windsurf’s equivalent of Cursor’s Composer) and extension compatibility.

I spent a frustrating afternoon figuring out why my favourite VS Code extensions weren’t working, and another hour optimising Cascade settings. This guide will save you that time.

Here’s everything you need to know to set up Windsurf IDE properly, from installation to your first AI-powered coding session.

Quick Start Summary

What You’ll Learn:
– How to download and install Windsurf IDE
– Initial configuration and account setup
– Installing and managing extensions
– Setting up Cascade AI mode
– Keyboard shortcuts and customisation
– Migrating from VS Code or Cursor

Prerequisites:
– macOS 10.15+, Windows 10+, or Linux
– 4GB RAM minimum (8GB recommended)
– Internet connection for AI features
– GitHub account (optional, for sync)

Time to Complete: 15-30 minutes for basic setup

Step 1: Download Windsurf IDE

System Requirements

Before installing, verify your system meets these requirements:

Minimum:
– macOS 10.15+, Windows 10+, or Ubuntu 18.04+
– 4GB RAM
– 500MB disk space
– Internet connection

Recommended:
– 8GB+ RAM (for large projects)
– SSD storage
– Stable internet (for Cascade AI features)

Installation Instructions

macOS Installation

Open the downloaded .dmg file
Drag “Windsurf” to the Applications folder
Open the Applications folder
Right-click Windsurf → “Open” (first time only, bypasses Gatekeeper)
Click “Open” in the security dialog

If you see the “unverified developer” warning:

# Run in Terminal to remove quarantine flag:
xattr -cr /Applications/Windsurf.app
Code language: PHP (php)

Windows Installation

Run the downloaded .exe installer
Choose installation type:
User Install (recommended, no admin required)
System Install (requires admin, all users)
Select installation location (default is fine)
Choose the “Add to PATH” option (recommended)
Click “Install”
Click “Finish” and launch Windsurf

If Windows Defender blocks:
– Click “More info” → “Run anyway”
– Windsurf is safe but new, so Windows may flag it

Linux Installation (Debian/Ubuntu)

# Download .deb package
wget https://codeium.com/download/windsurf-linux-x64.deb

# Install
sudo dpkg -i windsurf-linux-x64.deb

# Fix dependencies if needed
sudo apt-get install -f

# Launch
windsurf
Code language: PHP (php)

Linux Installation (Fedora/RHEL)

# Download .rpm package
wget https://codeium.com/download/windsurf-linux-x64.rpm

# Install
sudo rpm -i windsurf-linux-x64.rpm

# Launch
windsurf
Code language: PHP (php)

Step 2: First Launch and Account Setup

Welcome Screen

When you first launch Windsurf, you’ll see:

Welcome tab with quick start guide
Sign in prompt for Codeium account
Theme selection (dark/light)
Extension recommendations

Creating a Codeium Account

Windsurf’s AI features require a Codeium account:

Click the “Sign In” button in the top-right
Choose sign-in method:
GitHub (recommended, fastest)
GitLab
Google
Email
Authorise Windsurf in browser popup
Return to Windsurf (auto-signs in)

Free vs Pro:
– Free tier: Unlimited autocomplete, limited Cascade usage (~10 requests/day)
– Pro tier: $10/month, unlimited Cascade, faster responses, GPT-4 access

My recommendation: Start with the free tier, upgrade if you love Cascade mode.

Initial Configuration Wizard

Windsurf walks you through basic setup:

1. Choose a theme
– Dark+ (default, easy on eyes)
– Light+ (high contrast)
– Can change later in Settings

2. Select file icon theme
– Seti (default, colourful icons)
– Minimal (simple icons)
– None (no icons)

3. Import settings (optional)
– From VS Code
– From Cursor
– Start fresh

Step 3: Understanding the Windsurf Interface

Main UI Components

Windsurf’s interface mirrors VS Code:

Sidebar sections:
1. Explorer – File browser (Cmd+Shift+E)
2. Search – Find in files (Cmd+Shift+F)
3. Source Control – Git integration (Cmd+Shift+G)
4. Cascade – AI assistant (Cmd+Shift+L)
5. Extensions – Manage plugins (Cmd+Shift+X)

Key Differences from VS Code

What’s different:
– Cascade panel replaces generic chat (AI-powered multi-file editing)
– Supercomplete replaces basic autocomplete (context-aware suggestions)
– Flow mode for uninterrupted AI generation
– Custom command palette with AI shortcuts

What’s the same:
– File explorer and editing
– Terminal and debugging
– Git integration
– Extension system (mostly compatible)

Step 4: Setting Up Cascade AI Mode

Cascade is Windsurf’s killer feature—similar to Cursor’s Composer mode.

Opening Cascade

Three ways to open:

1. Keyboard shortcut (fastest)

Cmd+Shift+L (Mac)
Ctrl+Shift+L (Windows/Linux)

2. Sidebar icon
Click the “Cascade” icon in the left sidebar (looks like waves)

3. Command palette

Cmd+Shift+P → "Cascade: Open"
Code language: JavaScript (javascript)

Cascade Interface

Cascade Modes

Windsurf has three Cascade modes:

1. Auto Mode (default)
– AI decides which files to edit
– Best for: General features, multi-file changes
– Speed: Medium

2. Manual Mode
– You select files explicitly
– Best for: Precise edits, refactoring specific files
– Speed: Faster (less context to analyse)

3. Flow Mode
– Continuous generation without interruption
– Best for: Scaffolding, large features, boilerplate
– Speed: Slowest but most thorough

How to switch modes:
Click the mode dropdown at the top of the Cascade panel.

First Cascade Test

Let’s verify Cascade is working:

Open Cascade (Cmd+Shift+L)
Type this prompt:
Create a simple React component called HelloWorld that displays "Hello from Windsurf!"
Press Cmd+Enter to submit
Wait for response (5-15 seconds)
Review the generated code
Accept changes (click “Apply”)

If you see generated code → Cascade is working!

Step 5: Installing Essential Extensions

Windsurf supports most VS Code extensions.

How to Install Extensions

Method 1: Extensions marketplace
1. Click Extensions icon in sidebar (Cmd+Shift+X)
2. Search for extension name
3. Click “Install”
4. Reload Windsurf if prompted

Method 2: Command palette

Cmd+Shift+P → "Extensions: Install Extension"
Code language: JavaScript (javascript)

Recommended Extensions for Developers

Essential for everyone:

ESLint (dbaeumer.vscode-eslint)
JavaScript/TypeScript linting
Catches errors before runtime
Prettier (esbenp.prettier-vscode)
Code formatting
Auto-formats on save
GitLens (eamodio.gitlens)
Enhanced Git features
Inline blame, history, comparisons
Error Lens (usernamehw.errorlens)
Inline error display
See errors without hovering
Auto Rename Tag (formulahendry.auto-rename-tag)
Renames paired HTML/JSX tags
Huge time saver

Language-specific:

JavaScript/TypeScript:
– ES7+ React/Redux/React-Native snippets
– JavaScript (ES6) code snippets
– Path Intellisense

Python:
– Python (Microsoft)
– Pylance
– Python Debugger

Web Development:
– Live Server
– HTML CSS Support
– Tailwind CSS IntelliSense

Extensions That May Not Work

Some VS Code extensions are incompatible with Windsurf:

Known issues:
– GitHub Copilot – Conflicts with Windsurf’s AI (use Cascade instead)
– Cursor-specific extensions – Won’t install
– Some debugger extensions – May need Windsurf-specific versions

If extension fails:
1. Check Windsurf extension marketplace for alternatives
2. Report to Codeium support
3. Use VS Code for that specific task (temporarily)

Step 6: Configuring Settings

Opening Settings

Three ways to access:

Menu: Windsurf → Settings (Cmd+,)
Command Palette: Cmd+Shift+P → “Preferences: Open Settings”
Gear icon: Bottom-left corner → Settings

Important Settings to Configure

Editor Settings

{
  // Font (personal preference)
  "editor.fontFamily": "JetBrains Mono, Menlo, Monaco, 'Courier New'",
  "editor.fontSize": 14,
  "editor.fontLigatures": true,

  // Line height for readability
  "editor.lineHeight": 1.6,

  // Tab size (common standards)
  "editor.tabSize": 2,
  "editor.insertSpaces": true,

  // Auto save (avoid losing work)
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000,

  // Format on save
  "editor.formatOnSave": true,
  "editor.formatOnPaste": true,

  // Minimap (personal preference)
  "editor.minimap.enabled": false  // I find it distracting
}
Code language: JSON / JSON with Comments (json)

Cascade/AI Settings

{
  // Cascade default mode
  "windsurf.cascade.defaultMode": "auto",  // or "manual" or "flow"

  // Supercomplete (autocomplete) settings
  "windsurf.supercomplete.enabled": true,
  "windsurf.supercomplete.delay": 100,  // milliseconds before suggestions

  // Context awareness
  "windsurf.cascade.includeOpenFiles": true,
  "windsurf.cascade.includeRecentFiles": true,

  // Model selection (Pro only)
  "windsurf.cascade.model": "gpt-4"  // or "gpt-3.5" for speed
}
Code language: JSON / JSON with Comments (json)

Terminal Settings

{
  // Integrated terminal font
  "terminal.integrated.fontFamily": "JetBrains Mono",
  "terminal.integrated.fontSize": 13,

  // Default shell (customize per OS)
  "terminal.integrated.defaultProfile.osx": "zsh",
  "terminal.integrated.defaultProfile.windows": "PowerShell",

  // Terminal cursor
  "terminal.integrated.cursorStyle": "line",
  "terminal.integrated.cursorBlinking": true
}
Code language: JSON / JSON with Comments (json)

Git Settings

{
  // Auto fetch
  "git.autofetch": true,

  // Confirm before sync
  "git.confirmSync": false,

  // Default branch name
  "git.defaultBranchName": "main",

  // Show inline blame (with GitLens)
  "gitlens.currentLine.enabled": true
}
Code language: JSON / JSON with Comments (json)

Applying Settings

Option 1: UI settings editor
– Search for setting name
– Toggle or change value
– Auto-saves

Option 2: JSON settings file

Cmd+Shift+P → "Preferences: Open Settings (JSON)"
Code language: JavaScript (javascript)

Paste your JSON config, save.

Step 7: Keyboard Shortcuts

Essential Windsurf Shortcuts

Editor:

Action	Mac	Windows/Linux
Open Cascade	Cmd+Shift+L	Ctrl+Shift+L
Inline AI edit	Cmd+K	Ctrl+K
Accept suggestion	Tab	Tab
Reject suggestion	Escape	Escape
Next suggestion	Opt+]	Alt+]

Multi-cursor editing:

Action	Mac	Windows/Linux
Add cursor above	Cmd+Opt+↑	Ctrl+Alt+↑
Add cursor below	Cmd+Opt+↓	Ctrl+Alt+↓
Add a cursor at the selection	Cmd+D	Ctrl+D
Select all occurrences	Cmd+Shift+L	Ctrl+Shift+L

Customizing Shortcuts

Open keyboard shortcuts: Cmd+K Cmd+S
Search for the command
Click pencil icon → Press new keybinding
Save (auto-saves)

Step 8: Migrating from VS Code or Cursor

Importing VS Code Settings

Automatic import (during first launch):
– Windsurf detects VS Code
– Click “Import Settings”
– Select what to import (settings, extensions, keybindings)

Manual import (later):
1. Open Command Palette (Cmd+Shift+P)
2. Search “Settings Sync: Open Settings Sync”
3. Choose “Import from VS Code”

What gets imported:
– ✓ User settings (JSON)
– ✓ Keybindings
– ✓ Extensions list (Windsurf re-installs compatible ones)
– ✓ Snippets
– ✕ Copilot settings (not compatible)

Migrating from Cursor

Settings: Same process as VS Code (Cursor is also a fork)

Key differences to note:
– Cmd+K in Cursor = Inline edit (same in Windsurf)
– Cmd+Shift+I in Cursor (Composer) = Cmd+Shift+L in Windsurf (Cascade)
– Tab autocomplete works the same

Cursor projects work in Windsurf:
Just open the folder—no migration needed.

Keeping Both Editors Installed

You can run VS Code, Cursor, and Windsurf simultaneously:

Tips for multi-editor setup:
1. Different projects in different editors (test Windsurf on new projects)
2. Use VS Code for stable work, Windsurf for experimental
3. Settings don’t conflict (separate config directories)

Command-line differentiation:

# VS Code
code /path/to/project

# Cursor
cursor /path/to/project

# Windsurf
windsurf /path/to/project
Code language: PHP (php)

Step 9: First Project Setup

Opening a Project

Method 1: File menu

File → Open Folder → Select project directory

Method 2: Command line

windsurf /path/to/your/project

Method 3: Drag and drop
Drag project folder onto Windsurf icon

Initializing Workspace

When you open a project, Windsurf:

Indexes files for AI context (takes 5-30 seconds)
Detects language and suggests extensions
Scans for the git repository
Looks for package.json, requirements.txt, etc.

Wait for indexing to complete before using Cascade (for best results).

Recommended Project Structure

For the best Cascade performance, organise projects clearly:

my-project/
├── src/               # Source code
├── tests/             # Test files
├── docs/              # Documentation
├── .env.example       # Config examples
├── README.md          # Project overview
└── package.json       # Dependencies
Code language: PHP (php)

A clear structure helps AI understand your project.

Step 10: Optimising Performance

For Large Projects

If Windsurf feels slow on big codebases:

1. Exclude unnecessary files from indexing

Create .windsurfignore in project root:

node_modules/
dist/
build/
.git/
*.log
*.cache

2. Reduce the Cascade context window

{
  "windsurf.cascade.maxContextFiles": 10  // default: 20
}
Code language: JSON / JSON with Comments (json)

3. Disable features you don’t use

{
  "windsurf.supercomplete.enabled": false,  // if you prefer manual coding
  "editor.quickSuggestions": false
}
Code language: JSON / JSON with Comments (json)

For Slow Machines

Optimise for performance:

{
  "editor.minimap.enabled": false,
  "editor.wordWrap": "on",  // reduces horizontal scrolling work
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/dist/**": true
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true
  }
}
Code language: JSON / JSON with Comments (json)

Troubleshooting Common Issues

Issue #1: Cascade Not Responding

Symptoms: Cascade prompt hangs, no response

Solutions:
1. Check internet connection (AI requires a network)
2. Sign out and sign back in (refresh the auth token)
3. Check Codeium status: status.codeium.com
4. Restart Windsurf

Issue #2: Extensions Won’t Install

Symptoms: Extension install fails or errors

Solutions:
1. Check if extension is VS Code-compatible (most are)
2. Try installing from .vsix file directly
3. Check the extension compatibility list on Codeium docs
4. Report incompatible extensions to support

Issue #3: Slow Performance

Symptoms: Lag when typing, slow file switching

Solutions:
1. Close unused editor tabs
2. Add large folders to .windsurfignore
3. Disable unused extensions
4. Restart Windsurf (clears memory)
5. Check system resources (RAM, CPU)

Issue #4: Settings Not Persisting

Symptoms: Settings reset after restart

Solutions:
1. Check settings file permissions: ~/.windsurf/settings.json
2. Edit settings in JSON mode (not UI)
3. Avoid editing while Windsurf is running
4. Remove conflicting extensions

Issue #5: Cascade Generates Wrong Code

Symptoms: AI misunderstands prompts, wrong file edits

Solutions:
1. Be more specific in prompts (see Prompt Engineering Guide)
2. Switch Cascade to Manual mode (select files yourself)
3. Manually add context files to Cascade
4. Break large requests into smaller prompts

Comparing Windsurf to Alternatives

Windsurf vs Cursor

Windsurf advantages:
– Cheaper: $10/month vs $20/month for Pro
– More generous free tier: Unlimited autocomplete
– Faster updates: Newer product, rapid iteration

Cursor advantages:
– More mature: Better stability
– Larger community: More tutorials, support
– Composer is slightly better (in my testing)

My take: Try Windsurf first (free). If Cascade isn’t enough, upgrade to Cursor.

Windsurf vs GitHub Copilot

Windsurf advantages:
– Multi-file editing (Cascade mode)
– Full IDE (not just plugin)
– Better at refactoring large codebases

Copilot advantages:
– Works in any editor (VS Code, JetBrains, Vim, etc.)
– Faster autocomplete
– GitHub integration

My take: Use Copilot in VS Code, or use Windsurf for everything.

Windsurf vs VS Code + ChatGPT

Windsurf advantages:
– Direct code integration (no copy-paste)
– Context-aware (sees your entire project)
– Faster workflow (fewer tool switches)

VS Code + ChatGPT advantages:
– More flexible (any AI model)
– Better explanations (ChatGPT is more verbose)
– Free (if using free ChatGPT)

My take: Windsurf is more productive for actual coding. ChatGPT is better for learning concepts.

Best Practices Summary

Do:
– ✓ Sign in immediately (AI features require an account)
– ✓ Import settings from VS Code/Cursor (saves time)
– ✓ Install essential extensions first (ESLint, Prettier, GitLens)
– ✓ Configure auto-save (avoid losing work)
– ✓ Learn Cascade keyboard shortcut (Cmd+Shift+L)
– ✓ Wait for project indexing before using Cascade
– ✓ Write specific Cascade prompts (better results)

Don’t:
– ✕ Install GitHub Copilot (conflicts with Windsurf AI)
– ✕ Skip settings configuration (defaults aren’t optimal)
– ✕ Use Cascade on massive projects without .windsurfignore
– ✕ Accept AI-generated code without reviewing
– ✕ Forget to update Windsurf regularly (new features ship weekly)

Next Steps

Your Windsurf IDE is now set up and ready to use! To get the most out of it:

Practice with Cascade – Try building a small feature
Customise your workflow – Adjust settings to your preferences
Explore extensions – Install language-specific tools
Read related guides:
Cursor vs Windsurf – Detailed comparison
Prompt Engineering for AI Coding – Better Cascade prompts
Best AI Code Editors 2025 – See alternatives

FAQ

Is Windsurf IDE free?

Yes, Windsurf has a generous free tier with unlimited autocomplete and limited Cascade usage (~10 requests/day). Pro tier ($10/month) unlocks unlimited Cascade and GPT-4 access.

Can I use Windsurf without an internet connection?

Partially. The editor works offline, but AI features (Cascade, Supercomplete) require the internet. Basic editing, git, terminal, and debugging work offline.

Do I need to uninstall VS Code or Cursor?

No, you can keep all three installed. They don’t conflict and use separate settings directories. Many developers use multiple editors for different projects.

Will my VS Code extensions work in Windsurf?

Most will (90%+). Exceptions: GitHub Copilot, Cursor-specific extensions, and some debugger extensions. Install from the Windsurf marketplace to ensure compatibility.

How do I update Windsurf?

Windsurf auto-updates by default. Manual update: Help → Check for Updates. Or download the latest version from the website and reinstall (settings are preserved).

Can I use Windsurf for commercial projects?

Yes. The Pro license ($10/month) allows commercial use. Free tier is technically personal use only, but not strictly enforced. Check terms for your company’s policy.

Does Windsurf support remote development?

Not yet (as of January 2025). VS Code’s Remote – SSH extension doesn’t work in Windsurf. Use VS Code for remote work, or edit locally and deploy remotely.

How much data does Windsurf send to Codeium?

Windsurf sends code context to Codeium’s servers for AI processing. Your code is NOT stored or used for training. Read full privacy policy at codeium.com/privacy. For sensitive code, use local-only AI tools instead.

Last updated: January 2025

Pavan Mollagavelli

Updated December 15, 2025

Tutorials