Vim mode in Zed: setup, keys and settings

Three ways, all doing the same thing:

• First launch: tick the Vim mode checkbox on the welcome screen.
• Command palette: run workspace: toggle vim mode.
• Settings file: add "vim_mode": true to your user settings.

Esc takes you back to Normal mode as usual. For relative line numbers, set Zed's core "relative_line_numbers" to "enabled", or use the Vim setting toggle_relative_line_numbers (below) to have them only in Normal mode.

Vim options go in a "vim" object in your settings:

• "use_system_clipboard": "always" (the default), "never", or "on_yank". Unlike Vim, Zed uses the system clipboard by default; pick "never" if you want yanks to stay inside the editor.
• "use_smartcase_find": makes f and t case-insensitive when the letter you type is lowercase. Off by default.
• "toggle_relative_line_numbers": relative numbers in Normal mode, absolute in Insert mode. Off by default.
• "highlight_on_yank_duration": how long a yank is highlighted, in milliseconds (200 by default; 0 turns it off).
• "gdefault": makes :s replace every match on a line by default; the g flag then flips it back. Off by default.
• "default_mode": the mode new editors start in, "normal" by default.

One core setting matters too: "command_aliases" maps names you type at the : prompt to Zed commands, for example "W": "w".

Key bindings live in Zed's keymap.json (~/.config/zed/keymap.json on macOS and Linux); run zed: open keymap file from the command palette to open it. It holds an array, and each entry has a "context" that says when it applies and a set of "bindings". For j k to leave Insert mode, add this entry to the array:

• {
• "context": "vim_mode == insert",
• "bindings": { "j k": "vim::NormalBefore" }
• }

The contexts that matter for Vim are vim_mode == normal, visual, insert, replace, waiting and operator, and VimControl, which covers Normal, Visual and Operator-pending together. Combine them with && and ||, for example "Editor && vim_mode == normal".

The Zed docs include ready-made snippets for the most common requests: Ctrl-w with h j k l to move between docks and panes, subword motions for w, b and e (vim::NextSubwordStart and friends), s as a sneak motion (vim::PushSneak) instead of substitute, and giving Ctrl-c, Ctrl-v and Ctrl-f back to Zed.

Zed has its own versions of several favourite Vim plugins, on by default:

• Surround: ys, cs and ds, as in vim-surround.
• Comment: gcc in Normal mode, gc in Visual mode, as in vim-commentary.
• ReplaceWithRegister: gR. Exchange: cx.
• Indent navigation: [-, ]-, [+, ]+, [=, ]= jump by indentation level, as in vim-indentwise.
• Tree-sitter motions: ]m and [m for the next and previous method, ]] and [[ for sections, ]/ for comments.
• Insert mode completion: Ctrl-x Ctrl-o for completions, Ctrl-x Ctrl-l for code actions.

Zed's command line covers the everyday ones: :w, :wq, :q, :wa, :qa, :x, :up, splits (:sp, :vs, :new, :vne), tabs (:tabnew, :tabn, :tabp, :tabc), :bd and :ls. It also has jumps (:42, :$, :/foo), :s with ranges, :j, :d, :y, :sort and :sort i, and :set for wrap, number, relativenumber and ignorecase. Commands such as :E (explore), :te (terminal) and :G (git) open Zed's own panels.

What it doesn't do is take arguments: you can't name a file in :w newname.txt, and most of Vim's command-line power isn't emulated.

The Zed docs are upfront that Vim mode is not a one-to-one copy:

• Language-aware motions. Zed uses its own semantics in places: in Rust, % also jumps between matching | characters, and w treats $ as part of a word in JavaScript.
• Visual block mode is emulated with multiple cursors, so text you insert appears on every line as you type rather than when you press Esc.
• Macros use Zed's own recording, which can capture actions such as accepting a completion.
• Regex in search and :s uses ( and ) for groups instead of \( and \), and $1 instead of \1 in replacements. Searches are global by default.
• No vimrc and no Vim plugins. All configuration goes through Zed's settings and keymap.json.

For most editing, none of this gets in the way. The motions are the same as in Vim, and the course teaches them in a real editor in the browser.