Update, Uninstall, and Maintain Windsurf Guide

Knowing how to windsurf update and uninstall processes work prevents two common problems: running a stale version that has known bugs, and leaving residual data behind after an uninstall that causes issues with a fresh reinstall. Windsurf updates frequently, stores data across multiple directories, and does not always clean up completely when removed through the standard OS method.

This guide covers the full maintenance lifecycle -- how to keep the application current, where your data lives and how to back it up, how to move a configuration to a new machine, and what to do when the application starts behaving unexpectedly after an update.

Key Takeaways

• Windsurf updates are delivered in-app and require a restart: The application checks for updates automatically and notifies you when one is available -- accepting the update and restarting is the full process; no manual download is required.
• A complete uninstall requires more than deleting the application: Windsurf stores settings, extension data, logs, and cached AI context in directories outside the application bundle -- leaving these behind means a reinstall will inherit the old configuration.
• Local data is stored in predictable, platform-specific directories: Knowing where Windsurf stores its settings.json, extensions, and session logs gives you direct control over backup and migration without relying on any in-app tool.
• Migrating a configuration is a file copy operation: Moving your Windsurf setup to a new machine means copying three directories -- the settings directory, the extensions directory, and any project-level .windsurfrules files.
• Most post-update issues are caused by extension incompatibility: When Windsurf behaves unexpectedly after an update, the correct first diagnostic step is to disable all extensions and test whether the issue persists before investigating anything else.
• Codeium account data is cloud-synced: AI credits, account preferences, and subscription status are tied to your Codeium account, not the local install -- uninstalling Windsurf does not affect your account or credit balance.

Claude for Small Business

Claude for SMBs Founders

Most people open Claude and start typing. That works for one-off questions. It doesn't work for running a business. Do this once — this weekend.

Free Claude course for SMBs

How Do You Update Windsurf to the Latest Version?

Windsurf updates automatically in the background and notifies you when a new version is ready. Accepting the prompt, letting the download complete, and restarting the application is the full update process -- no manual download from windsurf.com is required for routine updates.

Check the update notification in the menu bar or trigger a manual check if the automatic prompt has not appeared.

• How automatic updates work: Windsurf checks for updates in the background and displays a notification badge or dialog when a new version is available -- accepting the prompt downloads the update and prompts for a restart to complete installation.
• Triggering a manual update check: If the automatic notification has not appeared, go to Help > Check for Updates in the menu bar -- this forces an immediate version check against the Codeium update server.
• Settings and extensions are not modified by updates: Windsurf updates the core application without touching user settings or installed extensions -- extensions are updated separately through the Extensions panel on their own cycle.
• Confirming the current version: The installed version number is visible in Help > About Windsurf (or Windsurf > About on macOS) -- cross-reference this against the release notes at windsurf.com to confirm you are on the latest build.
• Major updates may introduce new configuration options: After a significant version jump, new features may be available that are not enabled by default and require a deliberate opt-in from the settings panel.

After a major version update, revisiting Windsurf onboarding and setup tips helps new users confirm which newly introduced settings are worth enabling before the next session.

How Do You Completely Uninstall Windsurf?

A complete uninstall is two steps: remove the application using the standard OS method, then manually delete the residual data directories that the uninstaller leaves behind. Skipping the second step means a reinstall will inherit the old configuration.

Follow the platform-specific steps below -- the residual directory paths differ on each operating system.

• macOS uninstall step one: Drag Windsurf from the Applications folder to Trash and empty it -- this removes the application bundle but leaves all user data in place.
• macOS uninstall step two: Manually delete these directories using Finder (Go > Go to Folder to access hidden Library paths): ~/Library/Application Support/Windsurf, ~/Library/Logs/Windsurf, ~/Library/Caches/Windsurf, and ~/Library/.windsurf if present.
• Windows uninstall: Go to Settings > Apps > Installed Apps, locate Windsurf, and select Uninstall -- then manually delete %APPDATA%\Windsurf and %LOCALAPPDATA%\Windsurf to remove the settings and extension data the uninstaller leaves behind.
• Linux (.deb) uninstall: Run sudo dpkg -r windsurf or sudo apt remove windsurf in the terminal, then manually remove ~/.config/Windsurf and ~/.local/share/Windsurf to clear all residual data.
• Linux (AppImage) uninstall: Delete the AppImage file, then remove ~/.config/Windsurf and ~/.local/share/Windsurf from the terminal -- there is no package manager entry to remove for AppImage installs.

For developers running Windsurf alongside VS Code or IntelliJ, the Windsurf editor compatibility guide identifies which paths are shared between applications and need careful handling before a full uninstall.

What Settings and Data Does Windsurf Store Locally?

Windsurf stores four categories of local data: user settings (settings.json), installed extensions, keybindings (keybindings.json), and session logs. Account data, AI credits, and model preferences are stored in the Codeium cloud and are not affected by anything you do locally.

Know where each file lives before you back up, migrate, or delete anything.

• User settings (settings.json): Stored at ~/Library/Application Support/Windsurf/User/settings.json on macOS, %APPDATA%\Windsurf\User\settings.json on Windows, and ~/.config/Windsurf/User/settings.json on Linux -- this file contains all editor preferences, font settings, theme choices, and feature toggles.
• Installed extensions: Stored in a separate extensions directory (~/Library/Application Support/Windsurf/extensions on macOS, %USERPROFILE%.windsurf\extensions on Windows, and ~/.windsurf/extensions on Linux) -- each extension has its own subdirectory.
• Keybindings (keybindings.json): Stored alongside settings.json in the same User directory -- this file contains only customizations that differ from the default keybinding scheme, not the full keybinding map.
• Session and log data: Windsurf writes debug logs and crash reports to the platform-specific logs directory (~/Library/Logs/Windsurf on macOS) -- these files are not needed for backup and can be cleared to recover disk space.
• Codeium account and AI data: Credit balances, account preferences, and model selections are stored in your Codeium cloud account -- uninstalling Windsurf does not delete or affect any of this data.

Understanding Windsurf's core architecture clarifies which data categories are managed by the application automatically and which require manual intervention for backup or migration.

How Do You Back Up and Migrate Your Windsurf Configuration?

Backing up a Windsurf configuration means copying three items: settings.json, keybindings.json, and the extensions directory. Everything else -- logs, cache, session data -- can be left behind without affecting the restored environment on a new machine.

Copy the three items to a cloud drive, a dotfiles repository, or an external drive before migrating.

• Backing up settings files: Copy settings.json and keybindings.json from the User directory to a safe location -- these are plain text JSON files that can be version-controlled alongside a dotfiles repo if that is already part of your workflow.
• Backing up extensions: Copy the entire extensions directory to your backup location -- restoring it on a new machine means Windsurf will find the extension bundles already in place and activate them without a fresh download from the registry.
• Migrating to a new machine: On the destination machine, install Windsurf and complete first-launch authentication, then copy the backed-up settings.json, keybindings.json, and extensions directory to the corresponding platform-specific paths before the first launch.
• Project-level .windsurfrules files: These live in the project repository root, not in any Windsurf application directory -- they migrate automatically with the project and do not require a separate backup step.
• Timing matters for the migration copy: Copy the backup files before launching Windsurf on the new machine for the first time -- the application reads these files on startup, and pasting them in after launch may require a restart to take effect.

Before finalizing a backup procedure, reviewing Windsurf's built-in feature list confirms whether any features introduced in recent versions write data to paths outside the standard three-directory backup.

How Do You Troubleshoot Common Maintenance Issues?

Most post-update and post-reinstall problems fall into four categories: extension conflicts, expired authentication, settings permissions errors, and broken extension directory structures. Each has a direct diagnostic step that isolates the cause without guesswork.

Start with extensions -- they are the source of the majority of post-update issues.

• Windsurf behaves unexpectedly after an update: Disable all extensions using "Disable All Installed Extensions" in the Extensions panel, restart Windsurf, and test whether the problem persists -- if it resolves, re-enable extensions one at a time to identify the conflict.
• AI features stop working after an update or reinstall: Check authentication status in the Accounts panel -- if the session has expired or the token is stale, sign out and sign back in, then restart Windsurf to force a fresh token refresh.
• Settings not persisting between sessions: This usually indicates a permissions problem with the User directory -- check that Windsurf has write permission to the settings directory, which can silently revert on some OS update cycles.
• Extensions not loading after a manual migration: If extensions were copied from a backup but are not activating, check that the directory structure was preserved exactly -- Windsurf expects each extension in its own named subdirectory, and a flattened copy will not be recognized.
• Cascade returning degraded results after an update: Clear the Cascade conversation history and start a new session before assuming the issue is application-level -- stale context from a previous session can produce misleading results that resolve themselves with a fresh start.

Some issues that appear after updates are actually session-level context problems rather than application faults -- the guide to Cascade session best practices covers the habits that prevent these from accumulating.

Conclusion

Keeping Windsurf current, backed up, and cleanly removable requires knowing where the application stores its data. The three settings files and the extensions directory are the complete picture for most users. A complete uninstall is two steps: the OS-level removal and the manual deletion of the residual data directories.

Locate your settings.json and extensions directory now and add them to your backup routine before you need them. Recovering a configuration from backup takes minutes. Rebuilding it from scratch takes hours.

Claude for Small Business

Claude for SMBs Founders

Most people open Claude and start typing. That works for one-off questions. It doesn't work for running a business. Do this once — this weekend.

Free Claude course for SMBs

Want AI Development Tools Set Up and Maintained the Right Way?

At LowCode Agency, we are a strategic product team, not a dev shop. We design, build, and scale AI-powered products with a focus on architecture, performance, and shipping on time.

• AI-first product design: We build systems with AI at the core architecture layer, not added as an afterthought after launch.
• Full-stack delivery: Our team handles design, engineering, QA, and deployment end to end without gaps between handoffs.
• Agentic tooling expertise: We use Windsurf, Cursor, and agentic coding pipelines on real client projects, not just prototypes.
• Model selection guidance: We match the right AI model to each task, balancing cost, latency, and accuracy for the specific build.
• Code quality and review: Every deliverable goes through structured review before shipping, catching issues before they reach production.
• Scalable architecture: We build on foundations designed for growth so teams avoid rebuilding from scratch at the next inflection point.
• Flexible engagements: We engage on defined scopes, giving teams senior engineering capacity without the overhead of full-time hires.

We have built 350+ products for clients including Coca-Cola, American Express, Sotheby's, Medtronic, Zapier, and Dataiku.

Start a conversation with LowCode Agency to scope your project.