Flycheck practices

Table of Contents

Flycheck is a modern on-the-fly syntax checking extension for GNU Emacs 24, intended as replacement for the older Flymake extension which is part of GNU Emacs.

Flycheck 是 GNUE macs24 的动态语法检查扩展,目的是取代 GNU Emacs 中旧的 Flymake 扩展。

It uses various syntax checking and linting tools to check the contents of buffers, and reports warnings and errors directly in the buffer or in an optional error list (see Flycheck manual for more information):

通过各种语法检查和 lint 工具检查 buffer 内容,直接在 buffer 或可选的错误列表中报告警告和错误。

Out of the box Flycheck supports over 40 different programming languages with more than 80 different syntax checking tools, and comes with a simple interface to define new syntax checkers.

开箱即用的 Flycheck 支持超过 40 中不同的编程语言和超过 80 种不同的语法检查工具,并带有一个简单的接口可以定义新的语法检查器。

Many 3rd party extensions provide new syntax checkers and other features like alternative error displays or mode line indicators.


1 Introduction

Flycheck provides modern on-the-fly syntax checking extension for GNU Emacs 24, intended as replacement for the older Flymake extension which is part of GNU Emacs.

Flycheck 为 GNU Emacs 24 提供现代的动态语法检查,目的是取代 GNU Emacs 中的 Flymake 扩展。

Flycheck runs various linting tools and services to automatically check the contents of buffers while you are typing, and reports warnings and errors directly in the buffer, in the mode line and in an optional error list. You can navigate errors and warnings in the current buffer, show the corresponding messages, and copy errors to the kill ring.

Flycheck 运行各种 linting 工具和服务自动检查输入到 buffer 中的内容,在 buffer、模式行或可选的 error 列表中报告错误。可以在当前 buffer 中浏览错误和警告,显示相应的信息,拷贝错误到 kill ring 中。

  • Over 40 languages with more than 70 checkers. See Supported languages.

    超过 40 种语言和 70 款检查器。

  • Fully automatic, fail-safe, on-the-fly syntax checking in buffers

    全自动、防故障、动态检查 buffer。

  • In-buffer error highlighting, with fringe indicators

    buffer 中使用边缘标识高亮错误

  • Error navigation


  • Auto-updating error list


  • Many customisation options


  • A comprehensive manual


  • A simple API to add support for new languages and tools

    使用简单的 API 就可以添加新语言和工具。

  • A “doesn’t get in your way guarantee”


2 Installation

2.1 Prerequisites

Flycheck needs GNU Emacs 24. Older releases of GNU Emacs or other flavours of Emacs (e.g. XEmacs, Aquamacs, etc.) are not supported.

Flycheck 需要 GNU Emacs24。旧版 GNU Emacs 和其他种类的 Emacs 不受支持。

Flycheck works best on Unix-like operating systems. It is extensively tested on Linux and OS X.

Flycheck 在类 Unix 操作系统中工作良好。在 Linux 和 OS X 上经过广泛测试。

Flycheck does not explicitly support Windows, but tries to maintain Windows compatibility and should generally work fine on Windows, too. However, we can neither answer questions about Windows nor fix bugs that only occur on Windows without the help of active Windows users. Please watch out for known Windows issues!

Flycheck 没有明确支持 windows,但试图维护 windows 兼容性,在 windows 行也应该运行良好。不过,没有活跃的 windows 用户的帮助,我们也不能回答关于 windows 的问题,或修复发生在 windows 上的错误。

2.2 Syntax checking tools

Flycheck does not check buffers itself. It relies on external programs to check buffers, which need to be installed separately. See Supported languages, for a list of required programs for each language supported by Flycheck.

Flycheck 并不自己检查 buffer。它以来那些需要单独安装的外部工具检查 buffer。

Most of these programs are available in the package repositories of Linux distributions, or with the standard package managers of specific programming languages (e.g. Rubygems, NPM, Cabal, etc.)

大部分这种程序都能在 Linux 发行版的包容器中找到,或者在特定语言的标准包管理器中。(比如 Rubygems、NPM、Cacal 等)。

2.3 Installation

Install Flycheck via Emacs’ built-in package manager, from the MELPA Stable repository:

通过 Emacs 自带的包管理器或 MELPA 标准容器安装 Flycheck。

 M-x package-install RET flycheck

Alternatively, you may use the MELPA repository, which hosts the most recent development version. Note that these repositories are not included in GNU Emacs by default.

也可以使用 MELPA 容器,上次有最近的开发版本。注意 GNU Emacs 默认不包括这些容器。

You need to enable them explicitly, by adding the following to your init file:

可以通过在 init 文件中添加以下代码来显示启用他们:

(require 'package)
(add-to-list 'package-archives
             '("melpa" . "") t)

2.4 Cask

If you use Cask to manage your packages, add the following to your Cask file:

(source gnu)
(source melpa-stable)

(depends-on "flycheck")

3 Quickstart

3.1 Install and enable Flycheck

To get started with Flycheck, enable it by adding the following to your init file:

(add-hook 'after-init-hook #'global-flycheck-mode)

If you don’t know where your init file is take a look at the value of the variable user-init-file with C-h v user-init-file.

3.2 Install syntax checker tools

Next you need to install syntax checking tools for the major modes you are using. For instance, for Python you may want to install Pylint:

下一步需要安装正在使用的 major mode 对应的语法检查工具。

$ pip install pylint

For Ruby, you might want to use Rubocop and ruby-lint:

gem install rubocop ruby-lint

See Supported languages, for a complete list of all languages that Flycheck supports.

3.3 Check syntax in a buffer

Now switch to a Python or Ruby Mode buffer and run M-x flycheck-verify-setup to check whether Flycheck is correctly setup.

现在在 Python 或者 Ruby 模式 buff 中使用 flycheck-verif-setup 来检查是否正确设置了 Flycheck。

If everything is fine Flycheck will now check syntax using these tools, when you visit a buffer in any of these languages. Syntax checking happens automatically when you save the buffer or make any changes. Flycheck highlights errors and warnings in the buffer, indicates them in the fringe, and reports their numbers in the mode line.

一切设置好之后,当访问这些语言的任何 buffer 时,Flycheck 将会使用这些工具进行代码检查。当保存 buffer 或作出改变时会自动检查。Flycheck 高亮 buffer 中的错误和警告,使用边缘标记指示它们,并在模式行显示它们的数字。

You can also manually check a buffer with C-c ! c (flycheck-buffer). 可以使用 C-c!c 手动检查 buffer。

3.4 Navigate and list errors

Use C-c ! n (flycheck-next-error) and C-c ! p (flycheck-previous-error) to navigate between error locations. If you keep the point at an error location, Flycheck will show the error message in the echo area after a short delay. You can also hover error locations with the mouse and see the error message in a tooltip.

使用 C-c ! n (flycheck-next-error) and C-c ! p (flycheck-previous-error)在错误位置间进行导航。如果光标在 error 位置,短暂延迟后 Flycheck 会在回显区显示错误消息。也可以你使用鼠标悬位置,在 tooltip 中查看错误消息。

To get an overview of all errors and warnings in the current buffer, type C-c ! l (flycheck-list-errors) to pop up a list of all errors in your current buffer. The error list updates automatically when you fix errors or introduce new ones, or when you switch to another buffer.

为了得到当前 buffer 中所有错误和警告的概述,使用 C-c ! l(flycheck-list-error)来弹出当前 buffer 中所有错误的列表。当修正错误、引入新错误、或切换到新的 buff 时列表会自动更新。

3.4.1 More features

All Flycheck commands are available in the Emacs menu at ‘Syntax checking’ in the ‘Tools’ menu.

所有 Flycheck 命令都在 Emacs Tools 菜单下“Syntax checking”菜单中。

4 Usage

This chapter explains the usage of Flycheck in-depth.

本章深入讲解 Flycheck 的用法。

Note: All commands in this chapter are documented with their default key prefix C-c !. You can customise this prefix with flycheck-keymap-prefix, but remember your custom prefix while reading this chapter.

注意:本章的所有命令都是。可以通过 flycheck-keymap-prefix 定制该前缀,但是阅读本章的时候请记得定制的前缀。

4.1 Checking buffers

The minor mode flycheck-mode enables syntax checking in a single buffer. global-flycheck-mode automatically enables flycheck-mode all buffers whenever possible. You can exclude specific major modes from global-flycheck-mode with flycheck-global-modes.

flycheck-mode 辅助模式在单独的 buffer 中启用语法检查。globa-flycheck-mode 自动在所有 buffer 中启用 flycheck-mode。可用 flycheck-global-modes 从 global-flycheck-mode 中排除特定的主模式。

Note: global-flycheck-mode does not enable flycheck-mode for remote or encrypted files. The former is flaky and might be very slow, and the latter would leak confidential data to temporary directories. You may still check syntax in these buffers by manually enabling flycheck-mode with M-x flycheck-mode. However, this is not recommended for said reasons.

注意:global-flycheck-mode 不会远程或加密文件启用 flycheck-mode。前者可能是片段,并且非常慢。后者可能会泄露机密数据到临时目录。可以在这些目录中通过 M-x flycheck-mode 手动启用 flycheck-mode。然而,正如刚才所说原因并不推荐这样做。

Add the following code to your init file to enable syntax checking permanently:

将下面的代码添加到 init 文件来永久启用语法检查:

(add-hook 'after-init-hook #'global-flycheck-mode)

When flycheck-mode is enabled, Flycheck automatically checks a buffer whenever 启动 flycheck-mode 后,下面这些情况,Flycheck 会自动检查 buffer:

  • the buffer is saved,
  • new lines are inserted,
  • or a short time after you stopped to make changes to the buffer.

You can customise this behaviour by changing flycheck-check-syntax-automatically:

可以通过改变 flycheck-check-syntax-automatically 定制这种行为:

User Option: flycheck-check-syntax-automatically

A list of events that trigger a new syntax check in the current buffer:

当前 buffer 中触发语法检查的事件列表:

  • save

    Check the buffer immediately after it was saved.

    保存 buffer 后立即检查。

  • idle-change

    Check the buffer a short time after the last change to the buffer. The delay is customisable with flycheck-idle-change-delay.

    buffer 最后更改一段时间后检查。通过 flycheck-idle-change-delay 定制延迟时间。

  • new-line

    Check the buffer immediately after a new line was inserted.


  • mode-enabled

    Check the buffer immediately after Flycheck Mode was enabled.

    Flycheck mode 启用后立即检查。

For instance, with the following code in your init file Flycheck will only check the buffer when it is saved, but never while you are making changes to the buffer:

例如,如果 init 文件中是下面的代码,只有在保存 buffer 的时候才会检查,更改 buffer 不会检查。

(setq flycheck-check-syntax-automatically '(mode-enabled save))

In addition to automatic syntax checking you can always check the current buffer manually:

除了自动语法检查,还可以手动检查当前 buffer:

  • C-c ! c
  • M-x flycheck-buffer

    Check syntax in the current buffer.

Note: If syntax checking does not work, please check your setup:


  • C-c ! v
  • M-x flycheck-verify-setup

    Popup a buffer with information about the Flycheck setup for the current buffer.

    弹出显示当前 buffer 的 Flycheck 设置信息的 buffer。

    Lists the syntax checkers available for the current buffer, together with potential problems in their setup.

    显示可用于当前 buffer 的语法检查器,以及它们设置中可能存在的问题。

During syntax checks Flycheck creates temporary files to feed to contents of the current buffer to external programs. You can change the prefix used for the names of these temporary files with flycheck-temp-prefix.

语法检查过程中 Flycheck 创建临时文件将当前 buffer 内容传递给外部程序。可通过 flycheck-mtp-prefix 改变这些临时文件名字的前缀。

4.2 Syntax checkers

Flycheck does not check buffers by itself, but relies on external syntax checkers. When checking a buffer Flycheck automatically selects the best syntax checker from flycheck-checkers:

Flycheck 本身不会检查 buffer,而是依赖外部的语法检查器。检查时 Flycheck 自动从 flycheck-checkers 中选择最好的语法检查器:

User Option: flycheck-checkers

A list of all syntax checkers available for syntax checking.


A syntax checker in this list is a registered syntax checker.

Flycheck may apply further syntax checkers to the current buffer, if the selected syntax checker chains to other syntax checkers. For instance, the emacs-lisp syntax checker, which checks Emacs Lisp with Emacs’ byte compiler, chains to the emacs-lisp-checkdoc syntax checker, which checks Emacs Lisp for violations of documentation conventions, (elisp)Documentation Tips. In Emacs Lisp buffers, Flycheck will first use emacs-lisp, and then emacs-lisp-checkdoc.

如果选中的语法检查器关联其他检查器的话,Flycheck 可能会做进一步检查。例如,emacs-lisp 语法检查器使用 Emacs 的字节编译器检查 Emacs lisp,但它关联了检查 Emacs Lisp 是否违反文档约定 emacs-lisp-checkdoc 语法检查器。Emacs Lisp buffer 中,Flycheck 先使用 emacs-lisp,然后使用 emacs-lisp-checkdoc。

Flycheck ignores chained checkers which are not contained in flycheck-checkers.

Flycheck 忽略没有包含在 flycheck-chekcers 中的关联检查器。

Like everything else in GNU Emacs, syntax checkers have online documentation as well. If you are interested what major modes a particular syntax checker in flycheck-checkers supports, or what tool it uses, type C-c ! ?:

像 GNU Emacs 所有其他东西一样,语法检查器也有在线文档,如果有兴趣了解 flycheck-checkers 中的特定语法检查器支持哪种主模式,或者它使用什么工具,键入 C-c! ?:

  • C-c ! ?
  • M-x flycheck-describe-checker

    Prompt for a syntax checker and show its documentation.


    The documentation includes the name of the program or service used by the syntax checker, a list of major modes in which the checker will be used, and a list of its options.


Instead of letting Flycheck select a syntax checker automatically you can also explicitly tell Flycheck which checker to use for the current buffer, by manually selecting a specific syntax checker:

除了让 Flycheck 自动选择语法检查器,还可以为当前 buffer 手动选择 Flycheck 使用的检查器:

  • C-c ! s
  • M-x flycheck-select-checker

    Prompt for a syntax checker and select this syntax checker for the current buffer.

    输入检查器名字,为当前 buffer 选择该检查器。

  • C-u C-c ! s
  • C-u M-x flycheck-select-checker Remove any manual

    syntax checker selection for the current buffer, and let Flycheck automatically select a syntax checker from flycheck-checkers again.

    当前 buffer 语法检查器选项,再次让 Flycheck 从 flycheck-checkers 中自动选择语法检查器。

You can also select a syntax checker via the variable flycheck-checker. In fact, flycheck-select-checker just sets this variable accordingly:

也可以通过变量 flycheck-checker 选择语法选择器,事实上,flycheck-select-checker 只是设置了这个变量:

  • Variable: flycheck-checker

    A syntax checker to use for the current buffer.

    用于当前 buffer 的语法检查器。

    If nil (the default), Flycheck will automatically select the best checker from flycheck-checkers.

    如果为 nil(默认值),Flycheck 将会自动从 flycheck-checkers 中选择最好的检查器。

    If set to a syntax checker, Flycheck will use this syntax checker for the current buffer, and never automatically select any other. Flycheck still runs chained checkers, though.

    如果设置为一个语法检查器,Flycheck 会将该检查器用于当前 buffer,不再自动选择其他的。Flycheck 仍会运行关联的检查器。

    If the syntax checker selected by this variable does not work in the current buffer, Flycheck signals an error.

    如果该变量选中的检查器不能再 buffer 中工作,Flych 将会给出错误信号。

    You can set this variable locally. For instance, if your Python project mandates Flake8 as a syntax checker, you can tell Flycheck to only use the corresponding checker python-flake8 in Python files of your project by setting flycheck-checker as a directory-local variable in the top-level directory of your project with M-x add-dir-local-variable RET python-mode RET flycheck-checker RET python-flake8. See (emacs)Directory Variables, for more information about directory variables.

    可以将该变量设置为局部值。例如,如果 Python 项目将 Flake8 设置为语法检查器,Flycheck 对项目中的所有 python 文件只使用对应的检查器 python-flake8 检查。要这样做,需要在项目顶层目录中通过

    M-x add-dir-local-variable RET python-mode RET flycheck-checker RET python-flake8

    将 flycheck-checker 设置为局部目录变量。

Occasionally you may want to disable specific syntax checkers completely, so that they can never be used at all, neither via automatic nor via manual selection:


  • C-c ! x
  • M-x flycheck-disable-checker

    Prompt for a syntax checker to disable in the current buffer.

    提示要在当前 buffer 中关闭的语法选择器。

  • C-u C-c ! x
  • C-u M-x flycheck-disable-checker

    Prompt for a syntax checker to re-enable in the current buffer.

    提示要在当前 buffer 中重新启用的语法选择器。

This is particularly useful if you want to disable syntax checkers that are chained after others. For instance, if you do not care for documentation conventions of Emacs Lisp you may not need for the emacs-lisp-checkdoc checker, so you can disable it for the current buffer with M-x flycheck-disable-checker RET emacs-lisp-checkdoc.

这对于禁用被关联的语法检查器很有用。例如,如果不关心 Emacs Lisp 的文档约定,可能就不需要 emacs-lisp-checkdoc 检查器,所以可以使用 M-x flycheck-disable-checker RET emacs-lisp-checkdoc 禁用它。

flycheck-disable-checker actually sets the buffer-local value of the flycheck-disabled-checkers option:

flycheck-disable-checker 实际上是设置了 buff-local 值 flycheck-disabled-checkers 选项的 buffer-local 值:

  • User Option: flycheck-disabled-checkers

    A list of disabled syntax checkers. Flycheck will never use disabled syntax checkers to check a buffer.

    禁用的语法检查器列表。Flycheck 将不会使用禁用的语法检查器检查 buffer。

    You can customise this variable with M-x customize-variable RET flycheck-disabled-checkers or set its default value in your init file to permanently disable specific checkers. For instance, to permanently disable Clang for all C/C++ buffers:

    可以通过 M-x customize-variable RET flycheck-disabled-checkers 定制该变量,或者在 init 文件中将其值设置为永远禁用的指定检查器。例如,针对 C/C++ buffers 永远禁用 Clang。

    (setq-default flycheck-disabled-checkers '(c/c++-clang))

    You can also disable checkers via local variables. For instance, to disable emacs-lisp-checkdoc for your entire project, add it to flycheck-disabled-checkers in the .dir-locals.el file of your project:

    也可以通过局部变量禁用检查器。例如针对整个工程禁用 emacs-lisp-checkdoc,在工程的.dir-locals.el 文件中,将它添加到 flycheck-disable-checkers 变量中。

    ((emacs-lisp-mode (flycheck-disabled-checkers emacs-lisp-checkdoc)))

    See (emacs)Directory Variables, for more information about directory variables.

You can change the completion system used by the commands of this section with flycheck-completion-system.

可以通过 flycheck-completion-system 改变本节所有命令使用的补全系统。

4.3 Reporting results

When a syntax check in the current buffer has finished, Flycheck reports the results of the syntax checkers used by the check in the current buffer:

  • It highlights errors and warnings reported by a syntax checking in the buffer according to flycheck-highlighting-mode,
  • and indicates these locations in the fringe according to flycheck-indication-mode.

User Option: flycheck-highlighting-mode

How Flycheck highlights errors and warnings in the buffer:

  • lines

    Highlight the whole line, ignoring any column information.

  • columns

    Highlight the column of the error, if the error has a column, otherwise behave as lines.

  • symbols

    Highlight the symbol at the error column, if any, otherwise behave like columns. This is default

  • sexps

    Highlight the expression at the error column, if any, otherwise behave like columns. Warning: sexps can be very slow in some major modes, notably the built-in python-mode.

  • nil

    Do not highlight errors at all.

Flycheck uses the flycheck-error, flycheck-warning and flycheck-info faces to highlight errors, warnings and info messages respectively.

User Option: flycheck-indication-mode

How Flycheck indicates errors and warnings:

  • left-fringe
  • right-fringe

    Indicate errors in the left or right fringe respectively. See (emacs)Fringes, for more information about fringes.

    Flycheck uses the flycheck-fringe-error, flycheck-fringe-warning, and flycheck-fringe-info faces for the indicators for the corresponding error levels.

  • nil

    Do not indicate errors and warnings.

To avoid flooding a buffer with excessive reports, Flycheck discards any reports and disables the corresponding syntax checker subsequently, if the total number of reported errors of any level exceeds the value of flycheck-checker-error-threshold.

You can explicitly clear with the flycheck-clear command.

4.4 Navigating errors

By default, Flycheck integrates into standard error navigation commands of Emacs: M-g n (next-error) and M-g p (previous-error) will navigate between Flycheck warnings and errors in the current buffer. See (emacs)Compilation Mode, for more information about these commands. You can disable this integration by setting flycheck-standard-error-navigation to nil, and re-enabling flycheck-mode afterwards.

Note: With standard error navigation visible compilation buffers (e.g. from M-x compile, M-x grep, M-x occur, etc.) take precedence over Flycheck errors.

Flycheck provides an independent set of navigation commands which will always navigate Flycheck errors in the current buffer, regardless of visible compilation buffers and flycheck-standard-error-navigation:

  • C-c ! n
  • M-x flycheck-next-error

    Jump to the next error.

    With prefix argument, jump forwards by as many errors as specified by the prefix argument, e.g. M-3 C-c ! n will move to the 3rd error from the current point. With negative prefix argument, move to previous errors instead. Signal an error, if there are no more Flycheck errors.

  • C-c ! p
  • M-x flycheck-previous-error

    Jump to the previous Flycheck error.

    With prefix argument, jump backwards by as many errors as specified by the prefix argument, e.g. M-3 C-c ! p will move to the 3rd error before the current point. With negative prefix argument, move to next errors instead. Signal an error, if there are no more Flycheck errors.

    • M-x flycheck-first-error

      Jump to the first Flycheck error.

      With prefix argument, jump forwards to by as many errors as specified by the prefix argument, e.g. M-3 M-x flycheck-first-error moves to the 3rd error from the beginning of the buffer. With negative prefix argument, move to the last error instead.

By default, these commands consider all errors in the current buffer. With flycheck-navigation-minimum-level you can restrict them to errors above certain levels:

User Option: flycheck-navigation-minimum-level

The minimum levels of errors to consider for navigation.

If set to an error level, only navigate to errors whose level is as least as severe as this one. If nil, navigate to all errors.

4.5 Displaying errors

When the point moves to an error location Flycheck automatically displays the error at point after a short delay: User Option: flycheck-display-errors-delay

The number of seconds to wait before displaying the error at point. Floating point numbers can express fractions of seconds.

You can also display errors at point explicitly with C-c ! h:

  • C-c ! h
  • M-x flycheck-display-error-at-point

    Show the error(s) at point.

By default Flycheck shows the error message and the error ID in the echo area, but you can customise how Flycheck displays errors with flycheck-display-errors-function:

  • User Option: flycheck-display-errors-function

    A function to display errors. The function is called with a list of Flycheck error objects to display. See Errors, for more information about these objects.

Flycheck provides some built-in display functions:

  • Function: flycheck-display-error-messages

    Show error messages and IDs in the echo area.

  • Function: flycheck-display-error-messages-unless-error-list

    Like flycheck-display-error-messages, but does not show anything if the error list is visible. See Listing errors, for more information about the error list.

Alternatively the flycheck-pos-tip extension provides an display function which shows error messages in a graphical popup.

In addition to this display mechanism, Flycheck adds a tooltip to each error which appears when you hover the error location with the mouse pointer. You can force Emacs to show the contents of the tooltip in the echo area with C-h . (display-local-help).

The contents of this tooltip are created with flycheck-help-echo-function:

  • User Option: flycheck-help-echo-function

    A function to compute the contents of the error tooltips.

    By default Flycheck adds the error message and the error ID of all errors at point to the tooltip contents.

4.6 Killing errors

You can also put error messages into the kill ring:

  • C-c ! C-w
  • M-x flycheck-copy-errors-as-kill

    Copy all Flycheck error messages at point into the kill ring.

    Each error message is killed separately, so C-y (yank) only yanks a single error message. You can use M-y (yank-pop) to cycle between the killed messages after yanking the first one.

  • C-u C-c ! C-w
  • C-u M-x flycheck-copy-errors-as-kill

    Copy all Flycheck error messages at point, including their IDs.

  • M-0 C-c ! C-w
  • M-0 M-x flycheck-copy-errors-as-kill

    Copy the IDs of the errors at point.

4.7 Listing errors

4.8 Mode line display

4.9 Configuring checkers

5 Syntax checker definitions

6 Flycheck hooks

7 Flycheck API:

8 Supported languages

Author: lsl

Created: 2016-08-07 Sun 19:30