Command Line Interface

JuliaFormatter provides a command-line executable jlfmt for formatting Julia source code. This is a Pkg app, and therefore requires Julia v1.12 or later.

Installation

The app can be installed using Julia's app manager:

# Install the latest available version
import Pkg; Pkg.Apps.add("JuliaFormatter")

# Or a specific version. Note that the version must be >= v2.2.0 since that is
# when the `jlfmt` app was introduced.
import Pkg; Pkg.Apps.add(; name = "JuliaFormatter", version = v"2.3.0")

This should create a new binary, called jlfmt, inside the Julia depot's bin directory (usually ~/.julia/bin; but you can check with the DEPOT_PATH variable in Julia).

Alternatively, you can invoke the app directly without installation:

julia -m JuliaFormatter [<options>] <path>...

Quick Start

# Preview formatted output
jlfmt src/file.jl

# Check if files are already formatted with verbose mode
jlfmt --check -v src/

# Format files in-place with multiple threads
jlfmt --threads=6 -- --inplace -v src/

# Show diff without modifying
jlfmt --diff src/file.jl

Options

All formatting options can be passed to jlfmt as command-line arguments, e.g. --indent=2 --always-use-return=true.

In general the way that CLI options are specified are exactly the same as in .JuliaFormatter.toml, with some exceptions:

• When specified on the CLI options are hyphenated (e.g. --always-use-return), while in the config file they are underscored (e.g. always_use_return).
• To set an option to nothing, use --option=nothing (in the config file it would have to be option = "nothing").
• To pass a list of strings for variable_call_indent, specify the option multiple times on the CLI, e.g. --variable-call-indent=foo --variable-call-indent=bar (in the config file it would be variable_call_indent = ["foo", "bar"]).

You can run jlfmt --help for a full list of available options (the output of this is at the bottom of this page, to avoid clutter).

Configuration Files

jlfmt searches for .JuliaFormatter.toml configuration files starting from each input file's directory and walking up the directory tree.

A specific directory containing a configuration file can be specified with --config-dir:

# Search upwards from home directory for a config file
jlfmt --config-dir=~ src/file.jl

By default, command-line options override configuration file settings:

# Use indent=2 even if config file specifies indent=4
jlfmt --indent=2 src/file.jl

Use --prioritize-config-file to make configuration file settings take precedence (might be useful for language server integration):

jlfmt --prioritize-config-file --indent=2 src/file.jl

If you want to ignore preexisting configuration files, use --ignore-config (this is mostly useful for JuliaFormatter's own testing pipelines):

# Ignore any config files and use only CLI args
jlfmt --ignore-config --indent=2 src/file.jl

Configuration with stdin

When formatting from stdin, no configuration file is used by default. Use --config-dir to specify a directory for configuration file lookup:

# Format stdin using config from ./src directory
echo 'f(x,y)=x+y' | jlfmt --config-dir=./src

# Useful in editor integrations to respect project config
cat file.jl | jlfmt --config-dir=$(dirname file.jl)

The formatter will search for .JuliaFormatter.toml in the specified directory and its parent directories, just like it does for regular file inputs.

Conventions

jlfmt follows standard CLI conventions:

• Exit code 0 on success
• Exit code 1 on formatting errors or when --check detects unformatted files
• Formatted output to stdout (default) or in-place with --inplace
• Error messages to stderr

Help text

NAME
       jlfmt - An opinionated code formatter for Julia

SYNOPSIS
       jlfmt [<julia_options> --] [<options>] <path>...
       jlfmt [<julia_options> --] [<options>] -
       ... | jlfmt [<julia_options> --] [<options>]

       where <julia_options> are options passed to the Julia
       interpreter (e.g. --threads=auto), and <options> are
       options for JuliaFormatter.

DESCRIPTION
       `jlfmt` formats Julia source code using JuliaFormatter.jl.
       This tool can also be invoked as `julia -m JuliaFormatter`.

OPTIONS
       <path>...
           Input path(s) (files and/or directories) to process. For directories,
           all files (recursively) with the '*.jl' suffix are used as input files
           (also '*.md', '*.jmd', '*.qmd' if --format-markdown is specified).
           If no path is given, or if path is `-`, input is read from stdin.

       -h, --help
           Print this message.

       --version
           Print version information.

       -c, --check
           Check formatting without writing.

       -i, --inplace
           Format files in place.

       -d, --diff
           Print diff to stderr.

       -o <file>, --output=<file>
           File to write formatted output to.

       -v, --verbose
           Enable verbose output.

       --config-dir=<dir>
           Directory path for .JuliaFormatter.toml config lookup.

       --format-markdown=true|false
           Also format code blocks in Markdown files.

       --ignore=<pattern>
           Ignore files matching the given pattern. Can be repeated.

       --ignore-config
           Do not use .JuliaFormatter.toml config files.

       --lines=<start:stop>
           Only format the given range of lines. Can be repeated.

       --prioritize-config-file
           Prioritize config file options over command-line options.

       --stdin-filename=<name>
           Assumed filename when formatting from stdin.

FORMATTING OPTIONS
       These options control the formatting style. They can also be set in
       a `.JuliaFormatter.toml` config file.

       Note that options are merged from the config file and command-line
       arguments. If the same option is specified both a config file and
       command-line options are specified, the CLI arguments take priority
       by default. With `--prioritize-config-file`, the config file takes
       priority instead.

       If the same option is specified multiple times on the command line,
       the last value is used.

       --style=default|blue|sciml|yas|minimal
           Formatting style.

       --align-assignment=true|false
           Align assignment operators.

       --align-conditional=true|false
           Align conditional operators.

       --align-matrix=true|false
           Preserve whitespace alignment of matrix elements.

       --align-pair-arrow=true|false
           Align pair arrows (=>).

       --align-struct-field=true|false
           Align struct field type annotations.

       --always-for-in=true|false|nothing
           Normalise `in` to/from `=` in for loops.

       --always-use-return=true|false
           Add explicit 'return' statements to function definitions.

       --annotate-untyped-fields-with-any=true|false
           Annotate untyped struct fields with '::Any'.

       --conditional-to-if=true|false
           Convert ternary expressions to if/else blocks when over margin.

       --disallow-single-arg-nesting=true|false
           Prevent nesting of a single argument in parentheses.

       --for-in-replacement=in|=|∈
           Replacement for `=` in for loops when always_for_in is true.

       --force-long-function-def=true|false
           Force short-to-long function def transformation regardless of length.

       --format-docstrings=true|false
           Format docstrings.

       --import-to-using=true|false
           Convert 'import' to 'using'.

       --indent=<n>
           Indentation width.

       --indent-submodule=true|false
           Indent submodules appearing in the same file.

       --join-lines-based-on-source=true|false
           Join lines as they appear in the original source file.

       --long-to-short-function-def=true|false
           Convert long function definitions to short form.

       --margin=<n>
           Maximum line width.

       --normalize-line-endings=auto|unix|windows
           Normalize line endings.

       --pipe-to-function-call=true|false
           Convert pipe operator to function calls.

       --remove-extra-newlines=true|false
           Remove extra newlines.

       --sciml-margin-overrun=<n>
           Additional columns SciMLStyle may use.

       --separate-kwargs-with-semicolon=true|false
           Separate keyword arguments with a semicolon.

       --short-circuit-to-if=true|false
           Convert short-circuit operators to if-expressions.

       --short-to-long-function-def=true|false
           Convert short function definitions to long form.

       --surround-whereop-typeparameters=true|false
           Add curly braces around where type parameters.

       --trailing-comma=true|false|nothing
           Add trailing commas.

       --trailing-zero=true|false
           Add trailing zeros to floats.

       --transform-syntax-in-macros=true|false
           Apply syntax transformations inside macro calls.

       --v2-stable-multiline-strings=true|false
           Use stable multiline string length calculation.

       --variable-call-indent=<name>
           Allow variable indentation for calls to this function. Can be repeated.

       --whitespace-in-kwargs=true|false
           Add whitespace in keyword arguments.

       --whitespace-ops-in-indices=true|false
           Add whitespace around binary operations in indices.

       --whitespace-typedefs=true|false
           Add whitespace around '::' in type definitions.

       --yas-style-nesting=true|false
           Use YASStyle nesting rules in SciMLStyle.

EXAMPLES
       Format a file and write to stdout:
           jlfmt src/file.jl

       Format a file in place:
           jlfmt --inplace src/file.jl

       Format all files in a directory with the verbose mode:
           jlfmt --inplace --verbose src/

       Check if a file is formatted:
           jlfmt --check src/file.jl

       Format only lines 1-10 and 42-47 of a file:
           jlfmt --lines=1:10 --lines=42:47 src/file.jl

       Check if all files in a directory are formatted with multiple threads:
           jlfmt --threads=4 -- --check src/

       Show diff for formatting with 2-space indentations:
           jlfmt --diff --indent=2 src/file.jl

       Format from stdin (pipe):
           echo 'f(x,y)=x+y' | jlfmt

       Format from stdin (explicit):
           jlfmt - < input.jl

       Format from stdin using project config:
           echo 'f(x,y)=x+y' | jlfmt --config-dir=./src

       Use specific style:
           jlfmt --style=blue src/file.jl

       Combine options:
           echo 'for i=1:10; end' | jlfmt --always-for-in=true