User Manual

Only the latest stable standard library source is officially supported for use with rust-analyzer. If you are using an older toolchain or have an override set, rust-analyzer may fail to understand the Rust source. You will either need to update your toolchain or use an older version of rust-analyzer that is compatible with your toolchain.

If you are using an override in your project, you can still force rust-analyzer to use the stable toolchain via the environment variable RUSTUP_TOOLCHAIN. For example, with VS Code or coc-rust-analyzer:

This is the best supported editor at the moment. The rust-analyzer plugin for VS Code is maintained in tree.

You can install the latest release of the plugin from the marketplace.

Note that the plugin may cause conflicts with the previous official Rust plugin. The latter is no longer maintained and should be uninstalled.

The server binary is stored in the extension install directory, which starts with rust-lang.rust-analyzer- and is located under:

As an exception, on NixOS, the extension makes a copy of the server and stores it under ~/.config/Code/User/globalStorage/rust-lang.rust-analyzer.

Note that we only support the two most recent versions of VS Code.

Other editors generally require the rust-analyzer binary to be in $PATH. You can download pre-built binaries from the releases page. You will need to uncompress and rename the binary for your platform, e.g. from rust-analyzer-aarch64-apple-darwin.gz on Mac OS to rust-analyzer, make it executable, then move it into a directory in your $PATH.

On Linux to install the rust-analyzer binary into ~/.local/bin, these commands should work:

Make sure that ~/.local/bin is listed in the $PATH variable and use the appropriate URL if you’re not on a x86-64 system.

You don’t have to use ~/.local/bin, any other path like ~/.cargo/bin or /usr/local/bin will work just as well.

Alternatively, you can install it from source using the command below. You’ll need the latest stable version of the Rust toolchain.

If your editor can’t find the binary even though the binary is on your $PATH, the likely explanation is that it doesn’t see the same $PATH as the shell, see this issue. On Unix, running the editor from a shell or changing the .desktop file to set the environment should help.

Setting up rust-analyzer with a Flatpak version of Code is not trivial because of the Flatpak sandbox. While the sandbox can be disabled for some directories, /usr/bin will always be mounted under /run/host/usr/bin. This prevents access to the system’s C compiler, a system-wide installation of Rust, or any other libraries you might want to link to. Some compilers and libraries can be acquired as Flatpak SDKs, such as org.freedesktop.Sdk.Extension.rust-stable or org.freedesktop.Sdk.Extension.llvm15.

If you use a Flatpak SDK for Rust, it must be in your PATH:

If you want to use Flatpak in combination with rustup, the following steps might help:

A C compiler should already be available via org.freedesktop.Sdk. Any other tools or libraries you will need to acquire from Flatpak.

Prerequisites: You have installed the rust-analyzer binary.

To use rust-analyzer, you need to install and enable one of the two popular LSP client implementations for Emacs, Eglot or LSP Mode. Both enable rust-analyzer by default in rust buffers if it is available.

Prerequisites: You have installed the rust-analyzer binary. Not needed if the extension can install/update it on its own, coc-rust-analyzer is one example.

There are several LSP client implementations for Vim or Neovim:

GNOME Builder 3.37.1 and newer has native rust-analyzer support. If the LSP binary is not available, GNOME Builder can install it when opening a Rust file.

Support for Rust development in the Eclipse IDE is provided by Eclipse Corrosion. If available in PATH or in some standard location, rust-analyzer is detected and powers editing of Rust files without further configuration. If rust-analyzer is not detected, Corrosion will prompt you for configuration of your Rust toolchain and language server with a link to the Window > Preferences > Rust preference page; from here a button allows to download and configure rust-analyzer, but you can also reference another installation. You’ll need to close and reopen all .rs and Cargo files, or to restart the IDE, for this change to take effect.

Support for the language server protocol is built into Kate through the LSP plugin, which is included by default. It is preconfigured to use rust-analyzer for Rust sources since Kate 21.12.

To change rust-analyzer config options, start from the following example and put it into Kate’s "User Server Settings" tab (located under the LSP Client settings):

Then click on apply, and restart the LSP server for your rust project.

juCi++ has built-in support for the language server protocol, and since version 1.7.0 offers installation of both Rust and rust-analyzer when opening a Rust file.

Kakoune supports LSP with the help of kak-lsp. Follow the instructions to install kak-lsp. To configure kak-lsp, refer to the configuration section which is basically about copying the configuration file in the right place (latest versions should use rust-analyzer by default).

Finally, you need to configure Kakoune to talk to kak-lsp (see Usage section). A basic configuration will only get you LSP but you can also activate inlay diagnostics and auto-formatting on save. The following might help you get all of this.

Helix supports LSP by default. However, it won’t install rust-analyzer automatically. You can follow instructions for installing rust-analyzer binary.

There are multiple rust-analyzer extensions for Visual Studio 2022 on Windows:

Lapce has a Rust plugin which you can install directly. Unfortunately, it downloads an old version of rust-analyzer, but you can set the server path under Settings.

There is a package named ra_ap_rust_analyzer available on crates.io, for someone who wants to use it programmatically.

For more details, see the publish workflow.

Zed has native rust-analyzer support. If the LSP binary is not available, Zed can install it when opening a Rust file.

Source: annotations.rs

Provides user with annotations above items for looking up references or impl blocks and running/debugging binaries.

Source: auto_import.rs

Using the auto-import assist it is possible to insert missing imports for unresolved items. When inserting an import it will do so in a structured manner by keeping imports grouped, separated by a newline in the following order:

Example:

It is possible to configure how use-trees are merged with the imports.granularity.group setting. It has the following configurations:

In VS Code the configuration for this is rust-analyzer.imports.granularity.group.

The style of imports in the same crate is configurable through the imports.prefix setting. It has the following configurations:

In VS Code the configuration for this is rust-analyzer.imports.prefix.

Source: flyimport.rs

When completing names in the current scope, proposes additional imports from other modules or crates, if they can be qualified in the scope, and their name contains all symbols from the completion input.

To be considered applicable, the name must contain all input symbols in the given order, not necessarily adjacent. If any input symbol is not lowercased, the name must contain all symbols in exact case; otherwise the containing is checked case-insensitively.

→

Also completes associated items, that require trait imports. If any unresolved and/or partially-qualified path precedes the input, it will be taken into account. Currently, only the imports with their import path ending with the whole qualifier will be proposed (no fuzzy matching for qualifier).

→

To avoid an excessive amount of the results returned, completion input is checked for inclusion in the names only (i.e. in HashMap in the std::collections::HashMap path). For the same reasons, avoids searching for any path imports for inputs with their length less than 2 symbols (but shows all associated items for any input length).

It is possible to configure how use-trees are merged with the imports.granularity.group setting. Mimics the corresponding behavior of the Auto Import feature.

The feature is enabled only if the LSP client supports LSP protocol version 3.16+ and reports the additionalTextEdits (case-sensitive) resolve client capability in its client capabilities. This way the server is able to defer the costly computations, doing them for a selected completion item only. For clients with no such support, all edits have to be calculated on the completion request, including the fuzzy search completion ones, which might be slow ergo the feature is automatically disabled.

The feature can be forcefully turned off in the settings with the rust-analyzer.completion.autoimport.enable flag. Note that having this flag set to true does not guarantee that the feature is enabled: your client needs to have the corresponding capability enabled.

Source: view_item_tree.rs

Displays the ItemTree of the currently open file, for debugging.

Source: expand_macro.rs

Shows the full macro expansion of the macro at the current caret position.

Source: extend_selection.rs

Extends or shrinks the current selection to the encompassing syntactic construct (expression, statement, item, module, etc). It works with multiple cursors.

Source: file_structure.rs

Provides a tree of the symbols defined in the file. Can be used to

Source: references.rs

Shows all references of the item at the cursor location

Source: folding_ranges.rs

Defines folding regions for curly braced blocks, runs of consecutive use, mod, const or static items, and region / endregion comment markers.

Source: format_like.rs

"Result {result} is {2 + 2}" is expanded to the "Result {} is {}", result, 2 + 2.

The following postfix snippets are available:

Source: goto_declaration.rs

Navigates to the declaration of an identifier.

This is the same as Go to Definition with the following exceptions: - outline modules will navigate to the mod name; item declaration - trait assoc items will navigate to the assoc item of the trait declaration as opposed to the trait impl - fields in patterns will navigate to the field declaration of the struct, union or variant

Source: goto_definition.rs

Navigates to the definition of an identifier.

For outline modules, this will navigate to the source file of the module.

Source: goto_implementation.rs

Navigates to the impl items of types.

Source: goto_type_definition.rs

Navigates to the type of an identifier.

Source: highlight_related.rs

Highlights constructs related to the thing under the cursor:

Note: ?, | and → do not currently trigger this behavior in the VSCode editor.

Source: hover.rs

Shows additional information, like the type of an expression or the documentation for a definition when "focusing" code. Focusing is usually hovering with a mouse, but can also be triggered with a shortcut.

Source: inlay_hints.rs

rust-analyzer shows additional information inline with the source code. Editors usually render this using read-only virtual text snippets interspersed with code.

rust-analyzer by default shows hints for

Optionally, one can enable additional hints for

Note: inlay hints for function argument names are heuristically omitted to reduce noise and will not appear if any of the following criteria are met:

Source: interpret.rs

Source: join_lines.rs

Join selected lines into one, smartly fixing up whitespace, trailing commas, and braces.

See this gif for the cases handled specially by joined lines.

Source: lib.rs

In addition to usual reference completion, rust-analyzer provides some ✨magic✨ completions as well:

Keywords like if, else while, loop are completed with braces, and cursor is placed at the appropriate position. Even though if is easy to type, you still want to complete it, to get ` { }` for free! return is inserted with a space or ; depending on the return type of the function.

When completing a function call, () are automatically inserted. If a function takes arguments, the cursor is positioned inside the parenthesis.

There are postfix completions, which can be triggered by typing something like foo().if. The word after . determines postfix completion. Possible variants are:

There also snippet completions:

And the auto import completions, enabled with the rust-analyzer.completion.autoimport.enable setting and the corresponding LSP client capabilities. Those are the additional completion options with automatic use import and options from all project importable items, fuzzy matched against the completion input.

Source: matching_brace.rs

If the cursor is on any brace (<>(){}[]||) which is a part of a brace-pair, moves cursor to the matching brace. It uses the actual parser to determine braces, so it won’t confuse generics with comparisons.

Source: apply_change.rs

Clears rust-analyzer’s internal database and prints memory usage statistics.

Source: move_item.rs

Move item under cursor or selection up and down.

Source: on_enter.rs

rust-analyzer can override Enter key to make it smarter:

This action needs to be assigned to shortcut explicitly.

Note that, depending on the other installed extensions, this feature can visibly slow down typing. Similarly, if rust-analyzer crashes or stops responding, Enter might not work. In that case, you can still press Shift-Enter to insert a newline.

When using the Vim plugin:

Source: typing.rs

Some features trigger on typing certain characters:

Source: doc_links.rs

Retrieve a links to documentation for the given symbol.

The simplest way to use this feature is via the context menu. Right-click on the selected item. The context menu opens. Select Open Docs.

Source: parent_module.rs

Navigates to the parent module of the current module.

Source: runnables.rs

Provides a sneak peek of all tests where the current item is used.

The simplest way to use this feature is via the context menu. Right-click on the selected item. The context menu opens. Select Peek Related Tests.

Source: rename.rs

Renames the item below the cursor and all of its references

Source: runnables.rs

Shows a popup suggesting to run a test/benchmark/binary at the current cursor location. Super useful for repeatedly running just a single test. Do bind this to a shortcut!

Source: syntax_highlighting.rs

rust-analyzer highlights the code semantically. For example, Bar in foo::Bar might be colored differently depending on whether Bar is an enum or a trait. rust-analyzer does not specify colors directly, instead it assigns a tag (like struct) and a set of modifiers (like declaration) to each token. It’s up to the client to map those to specific colors.

The general rule is that a reference to an entity gets colored the same way as the entity itself. We also give special modifier for mut and &mut local variables.

Rust-analyzer currently emits the following token tags:

Token modifiers allow to style some elements in the source code more precisely.

Rust-analyzer currently emits the following token modifiers:

Source: fetch_crates.rs

Shows a view tree with all the dependencies of this project

Source: syntax_tree.rs

Shows the parse tree of the current file. It exists mostly for debugging rust-analyzer itself.

Source: status.rs

Shows internal statistic about memory usage of rust-analyzer.

Source: lib.rs

Search and replace with named wildcards that will match any expression, type, path, pattern or item. The syntax for a structural search replace command is <search_pattern> =⇒> <replace_pattern>. A $<name> placeholder in the search pattern will match any AST node and $<name> will reference it in the replacement. Within a macro call, a placeholder will match up until whatever token follows the placeholder.

All paths in both the search pattern and the replacement template must resolve in the context in which this command is invoked. Paths in the search pattern will then match the code if they resolve to the same item, even if they’re written differently. For example if we invoke the command in the module foo with a pattern of Bar, then code in the parent module that refers to foo::Bar will match.

Paths in the replacement template will be rendered appropriately for the context in which the replacement occurs. For example if our replacement template is foo::Bar and we match some code in the foo module, we’ll insert just Bar.

Inherent method calls should generally be written in UFCS form. e.g. foo::Bar::baz($s, $a) will match $s.baz($a), provided the method call baz resolves to the method foo::Bar::baz. When a placeholder is the receiver of a method call in the search pattern (e.g. $s.foo()), but not in the replacement template (e.g. bar($s)), then *, & and &mut will be added as needed to mirror whatever autoderef and autoref was happening implicitly in the matched code.

The scope of the search / replace will be restricted to the current selection if any, otherwise it will apply to the whole workspace.

Placeholders may be given constraints by writing them as ${<name>:<constraint1>:<constraint2>…​}.

Supported constraints:

Available via the command rust-analyzer.ssr.

Also available as an assist, by writing a comment containing the structural search and replace rule. You will only see the assist if the comment can be parsed as a valid structural search and replace rule.

Source: snippet.rs

rust-analyzer allows the user to define custom (postfix)-snippets that may depend on items to be accessible for the current scope to be applicable.

A custom snippet can be defined by adding it to the rust-analyzer.completion.snippets.custom object respectively.

In the example above:

The body field also has access to placeholders as visible in the example as $0. These placeholders take the form of $number or ${number:placeholder_text} which can be traversed as tabstop in ascending order starting from 1, with $0 being a special case that always comes last.

There is also a special placeholder, ${receiver}, which will be replaced by the receiver expression for postfix snippets, or a $0 tabstop in case of normal snippets. This replacement for normal snippets allows you to reuse a snippet for both post- and prefix in a single definition.

For the VSCode editor, rust-analyzer also ships with a small set of defaults which can be removed by overwriting the settings object mentioned above, the defaults are:

Source: view_crate_graph.rs

Renders the currently loaded crate graph as an SVG graphic. Requires the dot tool, which is part of graphviz, to be installed.

Only workspace crates are included, no crates.io dependencies or sysroot crates.

Source: view_hir.rs

Source: view_memory_layout.rs

Displays the recursive memory layout of a datatype.

Source: view_mir.rs

Source: symbol_index.rs

Uses fuzzy-search to find types, modules and functions by name across your project and dependencies. This is the most useful feature, which improves code navigation tremendously. It mostly works on top of the built-in LSP functionality, however # and * symbols can be used to narrow down the search. Specifically,

That is, # switches from "types" to all symbols, * switches from the current workspace to dependencies.

Note that filtering does not currently work in VSCode due to the editor never sending the special symbols to the language server. Instead, you can configure the filtering via the rust-analyzer.workspace.symbol.search.scope and rust-analyzer.workspace.symbol.search.kind settings. Symbols prefixed with __ are hidden from the search results unless configured otherwise.