Install Cursor and migrate from VS Code

Installing Cursor takes one package-manager command on each platform: brew install --cask cursor on macOS and Linux, or winget install Anysphere.Cursor on Windows. Cursor is built on VS Code, so extensions, settings, and keybindings carry over. Setup is finished only when the cursor command works and the agent answers from the project’s real files.

You install Cursor on a Friday afternoon, the window opens, and the agent replies to “hello”. On Monday you find that cursor . is not on your PATH, half your extensions did not come across, and the agent has been answering questions about a folder one level above your repository. Each of those is a two-minute fix on day one and an hour of confusion later.

This page is for the developer installing Cursor on a work machine for the first time, usually coming from VS Code. It ends with three checks that prove the install works without you inspecting anything by hand.

What this page checked

cursor.com could not be fetched on 2026-09-26. The install commands, the files each package manager downloads, the minimum macOS version, and where the cursor command comes from were checked against the Homebrew cask (Casks/c/cursor.rb) and the winget manifest (manifests/a/Anysphere/Cursor) on GitHub that day, and that check was not repeated on 2026-10-12. On 2026-10-12 Cursor’s release notes list Cursor 3.24 (2026-10-09) as the current release, and Cursor’s CLI docs give the agent CLI install in Install the Cursor agent CLI. Menu labels change between Cursor releases, so this page names settings by what they do rather than by their exact position in the UI.

What a finished Cursor install gives you

• Cursor from the 3.x line, installed through a channel that checks the download’s SHA-256 hash.
• The cursor shell command, so cursor . opens any repository from a terminal.
• Your VS Code extensions, settings, keybindings, and snippets, with a list of anything that did not transfer.
• A recorded answer from the agent that cites real files in your project and runs its test command, which is your proof that the editor, the terminal, and the agent’s view of the codebase all work.

Which install channel should you use?

Use a package manager unless your machine forbids one. Both the Homebrew cask and the winget manifest pin a SHA-256 hash for every download, so a corrupted or tampered installer fails instead of running. A manual download gets no such check.

Channel	Platforms	Installs the cursor command	Updates
Homebrew cask cursor	macOS 12 (Monterey) or later; Linux on x86_64 and arm64 (as an AppImage)	macOS: yes. Linux: no; link it yourself	macOS: Cursor updates itself; the cask is marked auto_updates, so brew upgrade leaves it alone. Linux: brew upgrade --cask cursor
winget Anysphere.Cursor	Windows on x64 and arm64	Check after install (see below)	winget upgrade Anysphere.Cursor, or Cursor’s own updater
Manual download from Cursor’s website	All	macOS and Linux: no; add it yourself	Cursor’s own updater

Package managers lag differently

On 2026-09-26 the winget manifest trailed the Homebrew cask by three minor versions. If a teammate on Windows reports a feature you cannot see, compare cursor --version output before you debug anything else. Cursor’s built-in updater usually closes the gap after the first launch.

Install Cursor on your platform

macOS

Run in a terminal:

brew install --cask cursor

The cask installs Cursor.app into /Applications and links its command-line launcher as cursor. Open a new terminal and confirm:

cursor --version

Without Homebrew, download the macOS installer from Cursor’s website, move Cursor to Applications, and add the cursor command as described in Add the cursor shell command.

If macOS refuses to open a manually downloaded copy because “the developer cannot be verified”, open System Settings > Privacy & Security, scroll to Security, and select Open Anyway. Do this only for a file you downloaded from cursor.com yourself.

Windows

Run in PowerShell:

winget install Anysphere.Cursor

The manifest ships two installers for each architecture: a per-user one that needs no administrator rights, and a machine-wide one. To choose explicitly, add --scope user or --scope machine. Most developers want user; IT-managed machines often want machine.

Open a new PowerShell window, so it picks up the updated PATH, and check the command:

where.exe cursor
cursor --version

If where.exe finds nothing, add the command from inside Cursor as described in Add the cursor shell command.

Linux

With Homebrew on Linux, the same cask installs the AppImage:

brew install --cask cursor

On Linux the cask does not create a cursor command. It moves the AppImage to ~/Applications/Cursor.AppImage and makes it executable; brew info --cask cursor shows the path if you changed Homebrew’s --appimagedir. Link it onto your PATH yourself:

mkdir -p ~/.local/bin
ln -sf ~/Applications/Cursor.AppImage ~/.local/bin/cursor
cursor --version

Without Homebrew, download the AppImage for your architecture (x86_64 or aarch64) from Cursor’s website. The file is named like Cursor-<version>-x86_64.AppImage. Put it somewhere permanent and put a cursor link on your PATH:

mkdir -p ~/Applications ~/.local/bin
mv ~/Downloads/Cursor-*-"$(uname -m)".AppImage ~/Applications/Cursor.AppImage
chmod +x ~/Applications/Cursor.AppImage
ln -sf ~/Applications/Cursor.AppImage ~/.local/bin/cursor
cursor --version

If cursor is not found, ~/.local/bin is not on your PATH; add export PATH="$HOME/.local/bin:$PATH" to ~/.bashrc or ~/.zshrc.

To get Cursor in your application launcher, create a desktop entry. The unquoted EOF lets the shell expand $HOME, because .desktop files do not expand ~:

cat > ~/.local/share/applications/cursor.desktop << EOF
[Desktop Entry]
Name=Cursor
Exec=$HOME/Applications/Cursor.AppImage %F
Terminal=false
Type=Application
StartupWMClass=Cursor
Categories=Development;IDE;
EOF

If the AppImage does not start, see When a Cursor install breaks: the two common causes are a missing FUSE 2 library and Ubuntu’s user-namespace restriction.

Add the cursor shell command

Skip this section if cursor --version already prints a version. The command matters because every later workflow on this site starts from a terminal in the repository: cursor ., cursor path/to/file.ts, and extension management with cursor --install-extension.

1. Open Cursor and open the Command Palette: Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows and Linux, as in VS Code.

2. Type shell command and run the entry that installs the cursor command in PATH.

3. Close every terminal window and open a new one. A running shell keeps its old PATH.

4. Check which binary answers. which -a cursor on macOS and Linux, where.exe cursor on Windows. The first line should point into your Cursor install, not at an old script or an alias.

On macOS, if the palette entry fails, link the launcher yourself. This is the same file the Homebrew cask links:

sudo mkdir -p /usr/local/bin
sudo ln -sf "/Applications/Cursor.app/Contents/Resources/app/bin/code" /usr/local/bin/cursor

Install the Cursor agent CLI

The cursor command opens the editor. Cursor’s agent also runs in a terminal through a separate CLI, and its command is agent (Cursor’s CLI docs, checked 2026-10-12). Skip this section if you only use the editor. On macOS, Linux and WSL, run:

curl https://cursor.com/install -fsS | bash

On Windows, run in PowerShell:

irm 'https://cursor.com/install?win32=true' | iex

Check the install with agent --version, start an interactive session with agent, and update with agent update. CLI builds are date-versioned, and the latest on 2026-10-12 is v2026.10.08.

Bring your VS Code setup into Cursor

When Cursor starts for the first time, it offers to import your VS Code extensions, settings, and keybindings. Accept it. If you skipped that screen, search Cursor Settings for “VS Code” to find the import option again.

Then prove the import instead of trusting it. With both code and cursor on your PATH, compare the extension lists:

macOS and Linux

diff <(code --list-extensions | sort) <(cursor --list-extensions | sort)

Lines starting with < are extensions VS Code has and Cursor does not. The <(...) syntax needs bash or zsh.

Windows

Compare-Object (code --list-extensions) (cursor --list-extensions)

Rows marked <= are extensions VS Code has and Cursor does not.

No output means the import is complete.

Migrate manually when the import misses something

The import can miss things with portable VS Code installs, VS Code Insiders, or a profile that is not the default. Copy the files yourself. Close Cursor first.

macOS

SRC="$HOME/Library/Application Support/Code/User"
DST="$HOME/Library/Application Support/Cursor/User"
mkdir -p "$DST"
cp "$SRC/settings.json" "$SRC/keybindings.json" "$DST/"
cp -R "$SRC/snippets" "$DST/"
code --list-extensions | xargs -n1 cursor --install-extension

Linux

SRC="$HOME/.config/Code/User"
DST="$HOME/.config/Cursor/User"
mkdir -p "$DST"
cp "$SRC/settings.json" "$SRC/keybindings.json" "$DST/"
cp -r "$SRC/snippets" "$DST/"
code --list-extensions | xargs -n1 cursor --install-extension

Windows

$src = "$env:APPDATA\Code\User"
$dst = "$env:APPDATA\Cursor\User"
New-Item -ItemType Directory -Force $dst | Out-Null
Copy-Item "$src\settings.json", "$src\keybindings.json" $dst
Copy-Item "$src\snippets" $dst -Recurse -Force
code --list-extensions | ForEach-Object { cursor --install-extension $_ }

An extension that Cursor’s extension marketplace does not carry fails with an error and the loop moves on. Those error lines are your review list: find an equivalent, or decide you do not need it. Re-run the comparison above until the only differences are ones you chose.

Settings that point at VS Code

A copied settings.json can hold paths and IDs that only make sense in VS Code, such as a Python interpreter path inside a VS Code-specific folder or a setting for an extension that did not install. Unknown keys only get a warning squiggle inside settings.json, so nothing fails at runtime; the feature is missing without a message. The tests in the next section are what surface it.

Prove the install works without reading anything by hand

An agent that answers “hello” proves only that you are signed in. A working install means three things: the agent sees the repository you opened, it can run the project’s own commands in the integrated terminal, and it tells you when it cannot. Each prompt below produces output you check against a fact you already know, so you do not have to read code to judge it.

Open a real repository, not an empty folder or your home directory. The agent indexes the folder you open, and its answers are only as good as that folder:

cd ~/src/your-service
cursor .

Sign in when Cursor asks. Indexing starts in the background, and you do not need to wait for it to finish.

Copy-paste prompt: prove the agent sees this repository

Do not edit any file. Answer from this repository only.
1. List the top-level directories and, for each, cite one file inside it by its relative path.
2. Name the command that runs this project's tests, and quote the exact line of the file where you found it (package.json, Makefile, pyproject.toml, or similar).
3. Name one thing you could not determine from the files, and say which file would have told you.
If a path you cite does not exist, say so instead of guessing.

Check the answer against what you know: every cited path should exist (ls it if unsure), and the quoted test command should match the file. Invented paths mean the agent is not grounded in this folder; see When a Cursor install breaks.

Copy-paste prompt: prove the agent can run your toolchain

Run this project's test command in the integrated terminal. Do not modify any file and do not install anything.
Report, in this order:
- the exact command you ran
- its exit code
- the last 20 lines of output
- whether the failure (if any) is an environment problem (missing runtime, missing dependency, wrong version) or a real test failure
Stop after reporting. Do not attempt a fix.

If Cursor asks for approval before running the command, approve it. The exit code is the evidence. Compare it with the result of running the same command yourself in a normal terminal: if yours passes and the agent’s fails, Cursor’s terminal is picking up a different runtime or PATH, and that is an install problem to fix now rather than a code problem to chase later.

Finally, record what you ran on. Paste this output into your team’s onboarding notes or the ticket for your setup, so the next “works on my machine” conversation starts from facts:

cursor --version
cursor --list-extensions | wc -l

The agent’s permissions for running commands unattended, and what it must never read, belong to the next page: essential Cursor configuration for agent work. The idea behind checking output against known facts instead of reading every line is covered in reading evidence instead of code.

When a Cursor install breaks

cursor: command not found. The shell predates the install, so open a new terminal. On macOS, run the Command Palette entry or create the link shown above. On Linux, check that ~/.local/bin is on PATH; if you installed with Homebrew, also check that you created the ~/.local/bin/cursor link from the Linux tab, because the cask does not create one. On Windows, sign out and back in if a new PowerShell window still cannot find it.

cursor . opens VS Code, or an old Cursor. Another cursor sits earlier on PATH, often a leftover alias or a copy from a previous manual install. which -a cursor (or where.exe cursor) lists every match in order. Remove the stale one, or check alias cursor in your shell profile.

macOS says Cursor “is damaged and can’t be opened”. The download was quarantined, often after being copied from another machine or a chat attachment. Delete it and reinstall with brew install --cask cursor, or download it again from cursor.com. Stripping the quarantine attribute with xattr also works, but it switches off Gatekeeper’s check for that copy, so do it only for a file you downloaded from cursor.com yourself.

The Linux AppImage exits with dlopen(): error loading libfuse.so.2. The AppImage needs the FUSE 2 library. Install it: sudo apt install libfuse2t64 on Ubuntu 24.04 and later, sudo apt install libfuse2 on older Ubuntu and Debian, sudo dnf install fuse-libs on Fedora, or sudo pacman -S fuse2 on Arch.

The Linux AppImage exits with a sandbox error on Ubuntu 23.10 or later. Ubuntu restricts unprivileged user namespaces, which Electron applications need for their renderer sandbox. sysctl kernel.apparmor_restrict_unprivileged_userns prints 1 when the restriction is active. Launching once with cursor --no-sandbox confirms the cause, but do not keep that flag in your desktop entry: it turns off the sandbox for every page Cursor renders. Grant the permission through an AppArmor profile for the AppImage instead, as your distribution documents.

The window opens blank or flickers. Start with cursor --disable-gpu. If that fixes it, update your graphics driver, or keep the flag for remote desktop sessions only.

Extensions are missing after the import. Run the extension comparison from Bring your VS Code setup into Cursor, then install the missing ones with cursor --install-extension PUBLISHER.NAME. An extension that fails there is not available in Cursor’s marketplace; look for an alternative.

The agent cites files that do not exist, or describes the wrong project. You opened the wrong folder (a parent directory, or your home directory), or the files the agent needs are excluded from indexing. Reopen with cursor . from the repository root, then check Cursor’s indexing status in Cursor Settings. Exclusions and ignore files are covered in context management in Cursor.

The agent stops with a usage or rate-limit message. You have reached your plan’s allowance. Model choice changes how fast you use it; see model selection. For other agent errors, see handling errors in Cursor.

Where to go after installing Cursor

Essential Cursor configuration for agent work A verify command, a run mode, project rules, and a stop hook, so the agent runs your checks unattended.

Project rules Give the agent your conventions once, in the repository, instead of in every prompt.

Cursor quick start The full quick-start sequence, from installation to your first shipped feature.

Install Claude Code instead The terminal-first alternative, if you want the agent outside an editor.

If you also use Codex, its setup is in Codex installation.