# rust-mode
**Repository Path**: mirrors_rust-lang/rust-mode
## Basic Information
- **Project Name**: rust-mode
- **Description**: Emacs configuration for Rust
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-09-25
- **Last Updated**: 2026-02-01
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# rust-mode
[](https://elpa.nongnu.org/nongnu/rust-mode.html)
[](https://melpa.org/#/rust-mode)
[](https://github.com/rust-lang/rust-mode/actions?query=workflow%3ACI)
**Table of Contents**
- [rust-mode](#rust-mode)
- [Introduction](#introduction)
- [Known issues](#known-issues)
- [Installation](#installation)
- [Melpa](#melpa)
- [Manual installation](#manual-installation)
- [Feature guide](#feature-guide)
- [Indentation](#indentation)
- [Code formatting](#code-formatting)
- [Prettifying](#prettifying)
- [Running / testing / compiling code](#running--testing--compiling-code)
- [Clippy](#clippy)
- [Easy insertion of dbg!](#easy-insertion-of-dbg)
- [More commands](#more-commands)
- [tree-sitter](#tree-sitter)
- [LSP](#lsp)
- [eglot](#eglot)
- [lsp-mode](#lsp-mode)
- [Auto-completion](#auto-completion)
- [Other recommended packages](#other-recommended-packages)
- [flycheck](#flycheck)
- [cargo.el](#cargoel)
- [cargo-mode](#cargo-mode)
- [rustic](#rustic)
- [Optional features](#optional-features)
- [For package maintainers](#for-package-maintainers)
- [Tests](#tests)
- [Contributing](#contributing)
## Introduction
`rust-mode` makes editing [Rust](http://rust-lang.org) code with Emacs
enjoyable. It requires Emacs 25 or later, and is included in both
[Emacs Prelude](https://github.com/bbatsov/prelude) and
[Spacemacs](https://github.com/syl20bnr/spacemacs) by default.
This mode provides:
- Syntax highlighting (for Font Lock Mode)
- Indentation
- Integration with Cargo, clippy and rustfmt
This mode does _not_ provide auto completion, or jumping to function /
trait definitions. See [Auto-completion](#auto-completion) below for tips on how
to enable this.
If you are missing features in rust-mode, please check out
[rustic](https://github.com/emacs-rustic/rustic) before you open a feature
request. It depends on rust-mode and provides additional features. This
allows us to keep rust-mode light-weight for users that are happy with
basic functionality.
## Known issues
- `rust-syntax-propertize` and `adaptive-wrap-prefix-mode` can lead to
severe lag when editing larger files
(https://github.com/brotzeit/rustic/issues/107)
## Installation
### Melpa
The package is available on MELPA. Add this to your init.el.
``` elisp
(require 'package)
(add-to-list 'package-archives
'("melpa" . "https://melpa.org/packages/") t)
(package-initialize)
(package-refresh-contents)
```
Now you can install `rust-mode` with:
`M-x package-install rust-mode`
And put this in your config to load rust-mode automatically:
`(require 'rust-mode)`
### NonGNU ELPA
[NonGNU ELPA](https://elpa.nongnu.org/) can be used out of the box in
emacs28.
For older versions you need to add something like the following to
your init file:
``` elisp
(with-eval-after-load 'package (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/")))
```
### Manual installation
Clone this repository locally, and add this to your init.el:
``` elisp
(add-to-list 'load-path "/path/to/rust-mode/")
(autoload 'rust-mode "rust-mode" nil t)
(add-to-list 'auto-mode-alist '("\\.rs\\'" . rust-mode))
```
## Feature guide
### Indentation
Commands like TAB should indent correctly.
The Rust style guide recommends spaces rather than tabs for
indentation; to follow the recommendation add this to your init.el,
which forces indentation to always use spaces.
```elisp
(add-hook 'rust-mode-hook
(lambda () (setq indent-tabs-mode nil)))
```
Since Emacs ≥ 24.4, [`electric-indent-mode`][] is turned on by
default. If you do not like it, call `(electric-indent-mode 0)` in
`rust-mode-hook`.
[`electric-indent-mode`]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Indent-Convenience.html
### Code formatting
The `rust-format-buffer` function will format your code with
[rustfmt](https://github.com/rust-lang/rustfmt) if installed. By
default, this is bound to C-c C-f.
The variable `rust-format-on-save` enables automatic formatting on
save. For example, add the following in your init.el to enable format
on save:
``` elisp
(setq rust-format-on-save t)
```
### Prettifying
You can toggle prettification of your code by running `M-x
prettify-symbols-mode`. If you'd like to automatically enable this
for all rust files, add the following to your init.el.
```elisp
(add-hook 'rust-mode-hook
(lambda () (prettify-symbols-mode)))
```
You can add your own prettifications to `rust-prettify-symbols-alist`.
For example, to display `x.add(y)` as `x∔(y)`, simply add to your init
file `(push '(".add" . ?∔) rust-prettify-symbols-alist)`.
### Running / testing / compiling code
The `rust-run`, `rust-test`, `rust-compile` and `rust-check` functions
shell out to Cargo to run, test, build and check your code. Under the
hood, these use the standard Emacs `compile` function.
By default these are bound to:
- C-c C-c C-u `rust-compile`
- C-c C-c C-k `rust-check`
- C-c C-c C-t `rust-test`
- C-c C-c C-r `rust-run`
To run programs requiring user input use universal argument when invoking
`rust-run` (C-u C-c C-c C-r).
### Clippy
`rust-run-clippy` runs
[Clippy](https://github.com/rust-lang/rust-clippy), a linter. By
default, this is bound to C-c C-c C-l.
### Easy insertion of dbg!
`rust-dbg-wrap-or-unwrap` either wraps or unwraps the current region
in `dbg!`. This can be useful for easily adding debug lines to your
program.
This is bound to C-c C-d by default.
### More commands
- `rust-toggle-mutability` toggle mut for var defined at current line
## tree-sitter
You can try the new native treesitter mode `rust-ts-mode` with:
```elisp
(use-package rust-mode
:init
(setq rust-mode-treesitter-derive t))
```
In case you want to use treesitter but can't use Emacs 29.1, you can
take a look at
[tree-sitter](https://github.com/emacs-tree-sitter/elisp-tree-sitter). When
the dependencies are installed you can activate the feature with:
```elisp
(use-package tree-sitter
:config
(require 'tree-sitter-langs)
(global-tree-sitter-mode)
(add-hook 'tree-sitter-after-on-hook #'tree-sitter-hl-mode))
```
## LSP
### eglot
A lightweight lsp client.
```elisp
(add-hook 'rust-mode-hook 'eglot-ensure)
```
### lsp-mode
Provides more features and you can enhance the functionality
by using additional packages. You can find more information in the
[lsp-mode wiki](https://emacs-lsp.github.io/lsp-mode/page/installation/#vanilla-emacs).
```elisp
(add-hook 'rust-mode-hook #'lsp)
```
## Auto-completion
You can either use a lsp client or [racer](https://github.com/racer-rust/racer)
with [emacs-racer](https://github.com/racer-rust/emacs-racer#installation).
Note that racer and rls are considered deprecated. You should use rust-analyzer
instead.
## Other recommended packages
### flycheck
[flycheck](https://github.com/flycheck/flycheck) allows highlighting
compile errors and Clippy lints inline.
### cargo.el
[cargo.el](https://github.com/kwrooijen/cargo.el) provides a minor
mode for integration with Cargo, Rust's package manager.
### cargo-mode
[cargo-mode](https://github.com/ayrat555/cargo-mode) is an Emacs minor
mode which allows to dynamically select a Cargo command. The reasons
behind this package can be found in [the
post](https://www.badykov.com/emacs/2021/05/29/emacs-cargo-mode/).
### rustic
[rustic](https://github.com/emacs-rustic/rustic) is based on rust-mode,
extending it with other features such as integration with LSP and with
flycheck.
## Optional features
The features of the following files can be disabled with `rust-load-optional-libraries`.
- rust-cargo.el
- rust-compile.el
- rust-playpen.el
- rust-rustfmt.el
They are disabled by default when you use rustic as it has its own implementations
for those features.
## Customization
`rust-cargo-default-arguments` set additional cargo args used for check,compile,run,test
## For package maintainers
### Tests
Run elisp tests:
``` bash
make test
```
## Contributing
Contributions are very welcome. We are also looking for additional maintainers.