Usage

This chapter explains in-depth how to use Flycheck for your daily work.

Note

All commands in this chapter are documented with their standard key prefix C-c !. If you do not like this prefix, you can change it with flycheck-keymap-prefix, but take care to remember your custom prefix while reading this chapter.

User Option flycheck-keymap-prefix

Variable properties

This variable may be risky if used as a file-local variable.

Prefix for key bindings of Flycheck.

Changing this variable outside Customize does not have any
effect.  To change the keymap prefix from Lisp, you need to
explicitly re-define the prefix key:

    (define-key flycheck-mode-map flycheck-keymap-prefix nil)
    (setq flycheck-keymap-prefix (kbd "C-c f"))
    (define-key flycheck-mode-map flycheck-keymap-prefix
                flycheck-command-map)

Please note that Flycheck's manual documents the default
keybindings.  Changing this variable is at your own risk.

This user option was introduced, or its default value was changed, in version 0.19 of the flycheck package.

Enabling syntax checking

global-flycheck-mode enables syntax checking in all buffers whenever possible:

M-x global-flycheck-mode

Toggle Flycheck Mode for all live buffers, and for new buffers.

With Global Flycheck Mode, Flycheck Mode is automatically enabled in all buffers, for which a suitable syntax checker exists and is enabled.

Note

Flycheck Mode will not be enabled in buffers for remote or encrypted files. The former is flaky and might be very slow, and the latter might leak confidential data to temporary directories.

You can still explicitly enable Flycheck Mode in such buffers with flycheck-mode. This is not recommended though.

User Option global-flycheck-mode

Whether Flycheck Mode is enabled globally.

To permanently enable syntax checking, either customize global-flycheck-mode with M-x customize-variable RET global-flycheck-mode and select Save for Future Sessions, or add the following code to your init file:

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

You can also explicitly enable syntax checking just for the current buffer with the local minor mode flycheck-mode:

M-x flycheck-mode

Toggle Flycheck Mode for the current buffer.

User Option flycheck-mode

Whether Flycheck Mode is enabled in the current buffer.

Checking buffers

When flycheck-mode is enabled, Flycheck automatically checks a buffer whenever

  • the buffer is saved (e.g. C-x C-s),
  • new lines are inserted,
  • or a short time (see flycheck-idle-change-delay) after the last change to the buffer.

You can customize this behaviour with the option flycheck-check-syntax-automatically:

User Option flycheck-check-syntax-automatically

Variable properties

This variable is safe as a file local variable if its value satisfies the predicate symbolp.

When Flycheck should check syntax automatically.

This variable is a list of events that may trigger syntax checks.
The following events are known:

`save'
     Check syntax immediately after the buffer was saved.

`idle-change'
     Check syntax a short time (see `flycheck-idle-change-delay')
     after the last change to the buffer.

`new-line'
     Check syntax immediately after a new line was inserted into
     the buffer.

`mode-enabled'
     Check syntax immediately when `flycheck-mode' is enabled.

Flycheck performs a syntax checks only on events, which are
contained in this list.  For instance, if the value of this
variable is (mode-enabled save), Flycheck will only check if
the mode is enabled or the buffer was saved, but never after
changes to the buffer contents.

If nil, never check syntax automatically.  In this case, use
`flycheck-buffer' to start a syntax check manually.

This user option was introduced, or its default value was changed, in version 0.12 of the flycheck package.

User Option flycheck-idle-change-delay

Variable properties

This variable is safe as a file local variable if its value satisfies the predicate numberp.

How many seconds to wait before checking syntax automatically.

After the buffer was changed, Flycheck will wait as many seconds
as the value of this variable before starting a syntax check.  If
the buffer is modified during this time, Flycheck will wait
again.

This variable has no effect, if `idle-change' is not contained in
`flycheck-check-syntax-automatically'.

This user option was introduced, or its default value was changed, in version 0.13 of the flycheck package.

You can also always check the current buffer manually:

C-c ! c
M-x flycheck-buffer
Check syntax in the current buffer.

Note

If syntax checking does not work, check your setup:

C-c ! v
M-x flycheck-verify-setup
Check whether Flycheck can be used in this buffer.

Display a new buffer listing all syntax checkers that could be
applicable in the current buffer.  For each syntax checkers,
possible problems are shown.

During syntax checks, Flycheck generates some temporary files for syntax checker input and output. Use flycheck-temp-prefix to change the prefix of these temporary files:

User Option flycheck-temp-prefix

Variable properties

This variable may be risky if used as a file-local variable.

Prefix for temporary files created by Flycheck.

This user option was introduced, or its default value was changed, in version 0.19 of the flycheck package.

Selecting syntax checkers

Whenever it checks a buffer, Flycheck selects a suitable syntax checker from flycheck-checkers:

User Option flycheck-checkers

Variable properties

This variable may be risky if used as a file-local variable.

Syntax checkers available for automatic selection.

A list of Flycheck syntax checkers to choose from when syntax
checking a buffer.  Flycheck will automatically select a suitable
syntax checker from this list, unless `flycheck-checker' is set,
either directly or with `flycheck-select-checker'.

You should not need to change this variable normally.  In order
to disable syntax checkers, please use
`flycheck-disabled-checkers'.  This variable is intended for 3rd
party extensions to tell Flycheck about new syntax checkers.

Syntax checkers in this list must be defined with
`flycheck-define-checker'.

An item in this list is a registered syntax checker.

To disable a registered syntax checker, add it to flycheck-disabled-checkers:

User Option flycheck-disabled-checkers

Variable properties

Automatically becomes buffer-local when set. This variable is safe as a file local variable if its value satisfies the predicate flycheck-symbol-list-p.

Syntax checkers excluded from automatic selection.

A list of Flycheck syntax checkers to exclude from automatic
selection.  Flycheck will never automatically select a syntax
checker in this list, regardless of the value of
`flycheck-checkers'.

However, syntax checkers in this list are still available for
manual selection with `flycheck-select-checker'.

Use this variable to disable syntax checkers, instead of removing
the syntax checkers from `flycheck-checkers'.  You may also use
this option as a file or directory local variable to disable
specific checkers in individual files and directories
respectively.

This user option was introduced, or its default value was changed, in version 0.16 of the flycheck package.

A syntax checker in flycheck-checkers that is not in flycheck-disabled-checkers is an enabled syntax checker.

Flycheck starts to check the current buffer with the first enabled and suitable syntax checker from flycheck-checkers. See Languages and syntax checkers for a list of all available syntax checkers. If there is no enabled and suitable checker for the current, Flycheck does not check this buffer. It does not signal an error. Instead a special mode line indicator informs about this state. See Mode line reporting for details.

You can also force Flycheck to use a specific syntax checker for the current buffer with flycheck-select-checker:

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

Select the syntax checker for the current buffer by setting flycheck-checker, and run a syntax check with the new syntax checker.

Prompt for a syntax checker and set flycheck-checker.

Any syntax checker can be selected with this command, regardless of whether it is enabled.

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

Deselect the current syntax checker, and run a syntax check with an automatically selected syntax checker.

Set flycheck-checker to nil.

Function flycheck-select-checker checker
Select CHECKER for the current buffer.

CHECKER is a syntax checker symbol (see `flycheck-checkers') or
nil.  In the former case, use CHECKER for the current buffer,
otherwise deselect the current syntax checker (if any) and use
automatic checker selection via `flycheck-checkers'.

If called interactively prompt for CHECKER.  With prefix arg
deselect the current syntax checker and enable automatic
selection again.

Set `flycheck-checker' to CHECKER and automatically start a new
syntax check if the syntax checker changed.

CHECKER will be used, even if it is not contained in
`flycheck-checkers', or if it is disabled via
`flycheck-disabled-checkers'.

You can change the completion system used by flycheck-select-checker:

User Option flycheck-completion-system
The completion system to use.

`ido'
     Use IDO.

     IDO is a built-in alternative completion system, without
     good flex matching and a powerful UI.  You may want to
     install flx-ido (see URL `https://github.com/lewang/flx') to
     improve the flex matching in IDO.

`grizzl'
     Use Grizzl.

     Grizzl is an alternative completion system with powerful
     flex matching, but a very limited UI.  See URL
     `https://github.com/d11wtq/grizzl'.

nil
     Use the standard unfancy `completing-read'.

     `completing-read' has a very simple and primitive UI, and
     does not offer flex matching.  This is the default setting,
     though, to match Emacs' defaults.  With this system, you may
     want enable option `icomplete-mode' to improve the display
     of completion candidates at least.

This user option was introduced, or its default value was changed, in version 0.17 of the flycheck package.

flycheck-select-checker sets the local variable flycheck-checker for the current buffer. You can also set this variable explicitly, via File Variables(emacs) or Directory Variables(emacs), to enforce a specific syntax checker per file or per directory:

Variable flycheck-checker

Variable properties

Automatically becomes buffer-local when set. This variable is safe as a file local variable if its value satisfies the predicate flycheck-registered-checker-p.

Syntax checker to use for the current buffer.

If unset or nil, automatically select a suitable syntax checker
from `flycheck-checkers' on every syntax check.

If set to a syntax checker only use this syntax checker and never
select one from `flycheck-checkers' automatically.  The syntax
checker is used regardless of whether it is contained in
`flycheck-checkers' or `flycheck-disabled-checkers'.  If the
syntax checker is unusable in the current buffer an error is
signaled.

A syntax checker assigned to this variable must be defined with
`flycheck-define-checker'.

Use the command `flycheck-select-checker' to select a syntax
checker for the current buffer, or set this variable as file
local variable to always use a specific syntax checker for a
file.  See Info Node `(emacs)Specifying File Variables' for more
information about file variables.

Like everything else in Emacs, a syntax checker has online documentation, which you can via with flycheck-describe-checker:

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

Show the documentation of a syntax checker.

Configuring syntax checkers

Syntax checker executables

For each syntax checker, there is a buffer-local, customizable variable flycheck-checker-executable, where checker is the name of the syntax checker.

The value of this variable is either nil, or a string. In the former case, Flycheck uses the default executable from the syntax checker definition when executing the syntax checker. In the latter case, it uses the value of the variable as executable.

Use these variables to override the executable from the definition per buffer. For instance, you could use a different Emacs version with the emacs-lisp or emacs-lisp-checkdoc.

You can either set these variables directly in your init.el, or change them interactively:

C-c ! e
M-x flycheck-set-checker-executable

Set the executable of a syntax checker in the current buffer.

Prompt for a syntax checker and an executable file, and set the executable variable of the syntax checker.

C-u C-c ! e
C-u M-x flycheck-set-checker-executable

Reset the executable of a syntax checker in the current buffer.

Prompt for a syntax checker and reset its executable to the default.

Syntax checker options

Some syntax checkers can be configured via options. See Supported languages for a complete list of options for each syntax checkers.

All options are customizable via M-x customize-group RET flycheck-options, and automatically buffer-local to easily set them in hooks.

Options are mainly intended to be used by extensions, and via File or Directory Local variables. See File Variables(emacs) and Directory Variables(emacs) respectively.

Syntax checker configuration files

Some syntax checkers also read configuration files, denoted by associated configuration file variables. See Supported languages of these variables.

All options are customizable via M-x customize-group RET flycheck-config-files, and automatically buffer-local to easily set them in hooks. You may also set them via File or Directory Local variables. See File Variables(emacs) and Directory Variables(emacs) respectively.

When set to a string, Flycheck tries to locate the configuration file using the functions in flycheck-locate-config-file-functions and passes the name of the file to the syntax checker:

User Option flycheck-locate-config-file-functions

Variable properties

This variable may be risky if used as a file-local variable.

Functions to locate syntax checker configuration files.

Each function in this hook must accept two arguments: The value
of the configuration file variable, and the syntax checker
symbol.  It must return either a string with an absolute path to
the configuration file, or nil, if it cannot locate the
configuration file.

The functions in this hook are called in order of appearance, until a
function returns non-nil.  The configuration file returned by that
function is then given to the syntax checker if it exists.

This variable is an abnormal hook.  See Info
node `(elisp)Hooks'.

With the default value of this variable, configuration files are located by the following algorithm:

  1. If the configuration file variable contains a path a directory separator, expand the path against the buffer’s default directory and use the resulting path as configuration file.
  2. If the buffer has a file name, search the buffer’s directory and any ancestors thereof for the configuration file.
  3. Eventually attempt to locate the configuration file in the user’s home directory.

If any of these steps succeeds, the subsequent steps are not executed.

Error reporting

When a syntax check in the current buffer has finished, Flycheck highlights the locations of errors and warnings in the buffer according to flycheck-highlighting-mode, and indicates these locations in the fringe according to flycheck-indication-mode. Additionally it shows the number of errors and warnings in the mode line.

Note

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

User Option flycheck-checker-error-threshold

Variable properties

This variable may be risky if used as a file-local variable.

Maximum errors allowed per syntax checker.

The value of this variable is either an integer denoting the
maximum number of errors per syntax checker and buffer, or nil to
not limit the errors reported from a syntax checker.

If this variable is a number and a syntax checker reports more
errors than the value of this variable, its errors are not
discarded, and not highlighted in the buffer or available in the
error list.  The affected syntax checker is also disabled for
future syntax checks of the buffer.

This user option was introduced, or its default value was changed, in version 0.22 of the flycheck package.

User Option flycheck-highlighting-mode

Variable properties

This variable is safe as a file local variable if its value satisfies the predicate symbolp.

The highlighting mode for Flycheck errors and warnings.

The highlighting mode controls how Flycheck highlights errors in
buffers.  The following modes are known:

`columns'
     Highlight the error column.  If the error does not have a column,
     highlight the whole line.

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

`sexps'
     Highlight the expression at the error column, if there is
     any, otherwise behave like `columns'.  Note that this mode
     can be *very* slow in some major modes.

`lines'
     Highlight the whole line.

nil
     Do not highlight errors at all.  However, errors will still
     be reported in the mode line and in error message popups,
     and indicated according to `flycheck-indication-mode'.

This user option was introduced, or its default value was changed, in version 0.14 of the flycheck package.

Face flycheck-error
Face flycheck-warning
Face flycheck-info

The faces to use to highlight errors, warnings and info messages respectively.

Note

The default faces provided by GNU Emacs are ill-suited to highlight errors because these are relatively pale and do not specify a background color or underline. Hence highlights are easy to overlook and even invisible for white space.

For best error highlighting customize these faces, or choose a color theme that has reasonable Flycheck faces. The popular Solarized and Zenburn themes are known to have good Flycheck faces.

User Option flycheck-indication-mode

Variable properties

This variable is safe as a file local variable if its value satisfies the predicate symbolp.

The indication mode for Flycheck errors and warnings.

This variable controls how Flycheck indicates errors in buffers.
May either be `left-fringe', `right-fringe', or nil.

If set to `left-fringe' or `right-fringe', indicate errors and
warnings via icons in the left and right fringe respectively.

If set to nil, do not indicate errors and warnings, but just
highlight them according to `flycheck-highlighting-mode'.
Face flycheck-fringe-error
Face flycheck-fringe-warning
Face flycheck-fringe-info

The faces of fringe indicators for errors, warnings and info messages respectively.

If you hover a highlighted error with the mouse, a tooltip with the top-most error message is shown. Alternatively, you can move the point onto an error location to see the error message. Flycheck displays errors at point after a short delay:

User Option flycheck-display-errors-delay

Variable properties

This variable is safe as a file local variable if its value satisfies the predicate numberp.

Delay in seconds before displaying errors at point.

Use floating point numbers to express fractions of seconds.

This user option was introduced, or its default value was changed, in version 0.15 of the flycheck package.

By default, Flycheck shows the messages and IDs of the errors at point in the minibuffer, but this behaviour is entirely customizable via the flycheck-display-errors-function option:

User Option flycheck-display-errors-function

Variable properties

This variable may be risky if used as a file-local variable.

Function to display error messages.

If set to a function, call the function with the list of errors
to display as single argument.  Each error is an instance of the
`flycheck-error' struct.

If set to nil, do not display errors at all.

Flycheck provides two built-in functions for this option:

Function flycheck-display-error-messages errors
Display the messages of ERRORS.

Concatenate all non-nil messages of ERRORS separated by empty
lines, and display them with `display-message-or-buffer', which
shows the messages either in the echo area or in a separate
buffer, depending on the number of lines.  See Info
node `(elisp)Displaying Messages' for more information.

In the latter case, show messages in
`flycheck-error-message-buffer'.
Function flycheck-display-error-messages-unless-error-list errors
Show messages of ERRORS unless the error list is visible.

Like `flycheck-display-error-messages', but only if the error
list (see `flycheck-list-errors') is not visible in any window in
the current frame.

See also

Listing errors

See also

The flycheck-pos-tip extension provides a display function to show errors at point in a graphical popup.

This user option was introduced, or its default value was changed, in version 0.13 of the flycheck package.

You can clear all errors in the current buffer with flycheck-clear:

C-c ! C
M-x flycheck-clear

Clear all Flycheck errors and warnings in the current buffer.

You should not normally need this command, because Flycheck checks the buffer periodically anyway.

Listing errors

To view all errors in the current buffer, pop up the error list with flycheck-list-errors:

C-c ! l
M-x flycheck-list-errors

List all errors in the current buffer in a separate buffer.

The error list automatically refreshes after a syntax check, and follows the current buffer and window, that is, if you switch to another buffer or window, the error list is updated to show the errors of the new buffer or window.

Every time the error list refreshes, flycheck-error-list-after-refresh-hook is run:

Hook flycheck-error-list-after-refresh-hook

Variable properties

This variable may be risky if used as a file-local variable.

Functions to run after the error list was refreshed.

This hook is run whenever the error list is refreshed.

This variable is a normal hook.  See Info node `(elisp)Hooks'.

This hook was introduced, or its default value was changed, in version 0.21 of the flycheck package.

When you move the point in the current buffer while the error list is visible, all errors on the current line are highlighted in the error list with flycheck-error-list-highlight:

Face flycheck-error-list-highlight
Flycheck face to highlight errors in the error list.

This face was introduced, or its default value was changed, in version 0.15 of the flycheck package.

You can customize the appearance of the line and column numbers and of the syntax checker name:

Face flycheck-error-list-line-number
Face for line numbers in the error list.

This face was introduced, or its default value was changed, in version 0.16 of the flycheck package.

Face flycheck-error-list-column-number
Face for line numbers in the error list.

This face was introduced, or its default value was changed, in version 0.16 of the flycheck package.

Face flycheck-error-list-checker-name
Face for the syntax checker name in the error list.

This face was introduced, or its default value was changed, in version 0.21 of the flycheck package.

Copying (killing) errors

Frequently, it’s convenient to not only see the error messages, but to also copy them into the kill ring:

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

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

Each error message is killed separately, so you can use M-y to cycle among the killed messages after yanking the first one with C-y.

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

Copy all Flycheck error messages and their IDs at the current point into kill ring.

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

Copy all Flycheck error IDs at the current point into kill ring. This command is particularly handy to copy an ID in order to add an inline suppression comment.

Mode line reporting

Flycheck always indicates its state in the mode line:

FlyC
There are no errors in the current buffer.
FlyC*
A syntax check is being performed currently.
FlyC:3/4
There are three errors and four warnings in the current buffer.
FlyC-
Automatic syntax checker selection did not find a suitable syntax checker. See Selecting syntax checkers for more information.
FlyC!
The syntax check failed. Inspect the *Messages* buffer for details.
FlyC?

The syntax check had a dubious result. The definition of the syntax checker may be flawed. Inspect the *Messages* buffer for details.

This indicator should never be displayed for built-in syntax checkers. If it is, please report an issue to the Flycheck developers, as by Reporting issues.

Change flycheck-mode-line to customize the mode line reporting:

User Option flycheck-mode-line

Variable properties

This variable may be risky if used as a file-local variable.

Mode line lighter for Flycheck.

The value of this variable is a mode line template as in
`mode-line-format'.  See Info Node `(elisp)Mode Line Format' for
more information.  Note that it should contain a _single_ mode
line construct only.

Customize this variable to change how Flycheck reports its status
in the mode line.  You may use `flycheck-mode-line-status-text'
to obtain a human-readable status text, including an
error/warning count.

You may also assemble your own status text.  The current status
of Flycheck is available in `flycheck-last-status-change'.  The
errors in the current buffer are stored in
`flycheck-current-errors', and the function
`flycheck-count-errors' may be used to obtain the number of
errors grouped by error level.

Set this variable to nil to disable the mode line completely.

This user option was introduced, or its default value was changed, in version 0.20 of the flycheck package.

See also

The flycheck-color-mode-line extension changes the background colour of the mode line according to the result of the last syntax check.