Formatting Options

JuliaFormatter is intended to be configurable and comes with a number of options to control the output of the formatter. Suggestions for more options are welcome; please open an issue!

All of these formatting options can be specified as:

• keyword arguments to JuliaFormatter.format, JuliaFormatter.format_text and JuliaFormatter.format_file
• entries in a .JuliaFormatter.toml file, or
• command-line arguments to the jlfmt command.

Below is a table of all the currently available formatting options, along with what each style sets each option to. Values that differ from DefaultStyle are shown in bold.

Note that, although styles each define a different set of options, they are not just collections of options; they also have unique formatting rules that are not captured by the options.

A note about options

Not all options are created equal. This section is intended to help you understand the implications of enabling certain options.

Syntax transformations

Some of the options below are more dangerous than others, because they perform syntax transformations (i.e., Meta.parse(format_text(s)) may not be equal to Meta.parse(s)). These options can therefore change the meaning of the code being formatted depending on the context, and should be used with caution.

To help you identify dangerous options, there is an emoji legend in the 'Kind' column:

• 📐: purely about whitespace
• ♻️: syntax normalisation — this does more than just whitespace as it can insert e.g. parentheses, but it does not change the AST in any way
• ⚠️: syntax transformation — this does change the AST, but the transformations are conservatively scoped and thus should be safe
• 🔥: dangerous syntax transformation — this can change the AST, and it is not actually possible to be conservative because that would defeat the entire purpose of the option.

Currently, only pipe_to_function_call is in the last category. Note that YASStyle and BlueStyle both enable pipe_to_function_call by default, so if you use either of those styles, you should be aware that this can change the meaning of your code!

As a guard against unwanted syntax transformations, by default, JuliaFormatter does not perform any syntax transformations inside macros or Exprs.

This can be overly cautious in some cases: many macros, such as @test and @inline, are completely agnostic to their contents. If you want to enable selected syntax transformations inside macros, you can set transform_syntax_in_macros to true. However, there is no option to enable syntax transformations inside Exprs as that changes the literal meaning of the Expr.

Options that can spoil idempotence

Some of the options below additionally have the potential to cause non-idempotent formatting if enabled (or, in the case of v2_stable_multiline_strings, if disabled). They are marked with a 🪃 emoji.

If you want to ensure idempotence, it is recommended to disable these options. If you absolutely must enable them, you may need to run the formatter multiple times to reach a fixed point: you can use the max_iterations option to control the number of passes JuliaFormatter will do.

align_...

Default: false

The align_assignment, align_conditional, align_pair_arrow, and align_struct_field options allow you to vertically align operators on consecutive lines. See the Custom Alignment page for more details and examples.

align_matrix

Default: false

If enabled, this option preserves pre-existing whitespace surrounding matrix elements in the original source file. If you want to align matrix elements yourself, you should set this to true.

using JuliaFormatter: format_text

# Elements left-aligned in original source
s = """
a = [
100 300 400
1   eee 40000
2   α   b
]"""

format_text(s, align_matrix=true) |> print

a = [
    100 300 400
    1   eee 40000
    2   α   b
]

# Elements right-aligned in original source
s = """
a = [
100 300   400
  1  ee 40000
  2   a     b
]"""

format_text(s, align_matrix=true) |> print

a = [
    100 300   400
      1  ee 40000
      2   a     b
]

always_for_in

Default: false

If true, iterators e.g. in for loops will always be formatted with in instead of =. The default replacement is in, but this can be changed with the for_in_replacement option. For example, to replace all = and in with ∈ in iterators, set for_in_replacement to "∈".

If false, JuliaFormatter still performs a very specific normalisation: for range iterators, e.g. for i = 1:10, JuliaFormatter uses =. For all other iterators, in is used.

If nothing, the choice between in and = is left to the user, and no normalisation is performed.

!!! Setting an option to nothing in .JuliaFormatter.toml TOML does not have a null value. To specify a nothing value in a .JuliaFormatter.toml file, set the option to the string "nothing", e.g. always_for_in = "nothing".

always_use_return

Default: false

If true, return will be prepended to the last expression in function definitions, macro definitions, and do blocks.

For example:

s = """
function foo()
    expr1
    expr2
end"""

using JuliaFormatter: format_text
format_text(s; always_use_return=true) |> println

function foo()
    expr1
    return expr2
end

A number of cases are skipped over:

• If the final expression is (already) return.
• If the final expression is a macro.
• If the final expression is a multiline block expression (e.g. if...end, begin...end, etc.). This includes calls with do blocks.
• If the final expression contains a return statement somewhere in it (e.g. cond ? (return 1) : (return 2)).
• If the final expression has a docstring attached to it.

Note that return is prepended to calls to functions such as throw(...) and error(). If you don't want this behaviour, add a return nothing at the end of the function (or just disable this option!). Click the "Show explanation" toggle below for a more detailed explanation of why I choose not to do this. (You may also be interested in the corresponding discussion on Runic.jl, which has the same behaviour.)

mythrow(x) = throw("error: \$x")

function f()
    do_other_stuff()
    f()  # This never returns, so maybe we shouldn't add return?!
end

annotate_untyped_fields_with_any

Default: true

Annotates fields in a type definitions with ::Any if no type annotation is provided:

s = """
struct A
    arg1
end
"""

using JuliaFormatter: format_text
format_text(s; annotate_untyped_fields_with_any=true) |> println

struct A
    arg1::Any
end

conditional_to_if

Default: false

If a ternary expression exceeds the margin, convert it into the equivalent if block:

s = "cond ? trueval : falseval"

using JuliaFormatter: format_text
format_text(s; margin=20, conditional_to_if=true) |> println

if cond
    trueval
else
    falseval
end

s = "foo(cond ? trueval : falseval)"
length(s)

30

out1 = format_text(s; margin=28, conditional_to_if=true)
println(out1)

foo(
    if cond
        trueval
    else
        falseval
    end,
)

out2 = format_text(out1; margin=28, conditional_to_if=true)
println(out2)

foo(if cond
    trueval
else
    falseval
end)

disallow_single_arg_nesting

Prevents the nesting of a single argument arg in parenthesis, brackets, and curly braces.

# Without `disallow_single_arg_nesting`:
function_call(
    "String argument"
)
[array_item(
    10
)]
{key => value(
    "String value"
)}

# With `disallow_single_arg_nesting` enabled:
function_call("String argument")
[array_item(10)]
{key => value("String value")}

for_in_replacement

Can be used when always_for_in is true to replace the default in with ∈ (\\in), or = instead. The replacement options are ("in", "=", "∈").

for a = 1:10
end

# formatted with always_for_in = true, for_in_replacement = "∈"
for a ∈ 1:10
end

force_long_function_def

Default: false

If true, tweaks the behavior of short_to_long_function_def to force the transformation no matter how short the function definition is.

format_docstrings

Default: false

Format code docstrings with the same options used for the code source.

Markdown is formatted with CommonMark alongside Julia code.

import_to_using

Default: false

If true, import expressions are rewritten to equivalent using expressions:

s = """
import A
import B, C, D"""

using JuliaFormatter: format_text
format_text(s; import_to_using=true) |> println

using A: A
using B: B
using C: C
using D: D

There are some exceptions to this, which makes this transformation quite conservative:

• This transformation is disabled inside macros or Exprs.

• import X as Y cannot be rewritten in a semantically equivalent way, so is skipped.

• import A.b cannot be properly resolved (it may either be using A: b or using A.b: b), so is skipped.

• import ..X cannot be rewritten because X may not necessarily be a module. See e.g. this issue.

indent

Default: 4

The number of spaces used for one level of indentation.

There is at present no option to use tabs for indentation: please open an issue if you want this feature.

indent_submodule

Default: false

When set to true, submodule(s) appearing in the same file will be indented.

module A
a = 1

module B
b = 2
module C
c = 3
end
end

d = 4

end

will be formatted to:

module A
a = 1

module B
    b = 2
    module C
        c = 3
    end
end

d = 4

end

join_lines_based_on_source

Default: false

When true lines are joined as they appear in the original source file.

function foo(arg1,
                       arg2, arg3
                       )
       body
end

When false and the maximum margin is > than the length of "function foo(arg1, arg2, arg3)" this is formatted to

function foo(arg1, arg2, arg3)
    body
end

When true, arg1 and arg2, arg3 will remain on separate lines even if they can fit on the same line since it's within maximum margin. The indentation is dependent on the style.

function foo(arg1,
    arg2, arg3,
)
end

There are exceptions to this:

if a body1 elseif b body2 else body3 end

will be formatted to the following, even if this option is set to true:

if a
    body1
elseif b
    body2
else
    body3
end

long_to_short_function_def

Default: false

Transforms a long function definition

function f(arg2, arg2)
    body
end

to a short function definition if the short function definition does not exceed the maximum margin.

f(arg1, arg2) = body

See also: short_to_long_function_def.

margin

Default: 92

The maximum length of a line. Code exceeding this margin will, in general, be formatted across multiple lines.

max_iterations

Default: 1

JuliaFormatter is intended to be idempotent, meaning that formatted code should not change if formatted again. However, with certain options enabled, this may not be the case. (Please see the top of this page for more information!)

This option exists in order to allow you to perform multiple rounds of formatting, if you wish to. Note that this will cause formatting to be slower. JuliaFormatter will format the code up to max_iterations times, stopping if the code is unchanged after a formatting pass.

normalize_line_endings

Default: "auto"

One of "unix" (normalize all \r\n to \n), "windows" (normalize all \n to \r\n), "auto" (automatically choose based on which line ending is more common in the file).

pipe_to_function_call

Default: false

If true, x |> f is rewritten to f(x), and x .|> f to f.(x).

remove_extra_newlines

Default: false

If true, superfluous newlines will be removed. For example:

module M



a = 1

function foo()


    return nothing

end


b = 2


end

is rewritten as

module M

a = 1

function foo()
    return nothing
end

b = 2

end

Modules are the only type of code block where it is permissible to keep a single newline prior to the initial or after the final piece of code.

sciml_margin_overrun

Default: 20

Additional columns SciMLStyle may use when a slightly over-margin line is more readable than an aggressive line break. Set this to 0 to make SciML soft-margin checks strict.

This option has no effect for other styles.

separate_kwargs_with_semicolon

Default: false

When set to true, keyword arguments in a function call will be separated with a semicolon.

s = "f(a, b = 1)"

using JuliaFormatter: format_text
format_text(s; separate_kwargs_with_semicolon=true) |> println

f(a; b = 1)

This transformation is disabled in several cases:

• Inside macros or Exprs.

• In the signature of a function definition. For example, these are different:

  function f(a, b = 1)  # b is an optional positional argument
      body
  end
  
  function f(a; b = 1)  # b is a keyword argument
      body
  end

• When the function call does not have a semicolon, but has positional arguments after keyword arguments. For example, f(p, q=r, s) is not transformed. See this issue for details.

short_circuit_to_if

If true, converts logical operators to the equivalent if-expression, if it is clear that the value is not used.

In particular, a && f() is converted to if a; f(); end, and a || f() is converted to if !a; f(); end.

s = """
function foo(a, b)
    a || return "bar"
    b && return "ooo"
    return 5
end"""

using JuliaFormatter: format_text
format_text(s; short_circuit_to_if=true) |> println

function foo(a, b)
    if !(a)
        return "bar"
    end
    if b
        return "ooo"
    end
    return 5
end

In general these are only converted if they are a top-level statement inside a block. If the value of the logical operator is in any way used, it will not be converted. These include:

• Conditions in if, elseif, and while statements.
• The value being assigned to a variable or otherwise being part of some expression.
• The value being returned (including implicitly, by being the last statement in a block).

short_to_long_function_def

Default: false

Transforms a short function definition

f(arg1, arg2) = body

to a long function definition if the short function definition exceeds the maximum margin, or if force_long_function_def is set to true.

function f(arg2, arg2)
    body
end

See also: long_to_short_function_def.

This transformation is disabled inside macros or Exprs.

surround_whereop_typeparameters

Default: true

If true, surrounds type parameters with curly braces if the braces are not already present.

function func(...) where TPARAM
end

becomes

function func(...) where {TPARAM}
end

trailing_comma

Default: true

One of true, false, or nothing.

Trailing commas are added after the final argument when nesting occurs and the closing punctuation appears on the next line.

For example when the following is nested (assuming DefaultStyle):

funccall(arg1, arg2, arg3)

it turns into:

funccall(
    arg1,
    arg2,
    arg3, # trailing comma added after `arg3` (final argument) !!!
)

• When set to true, the trailing comma is always added during nesting.
• When set to false, the trailing comma is always removed during nesting.
• When set to nothing, the trailing comma appears as it does in the original source.

!!! Setting an option to nothing in .JuliaFormatter.toml TOML does not have a null value. To specify a nothing value in a .JuliaFormatter.toml file, set the option to the string "nothing", e.g. always_for_in = "nothing".

trailing_zero

Default: true

Add a trailing zero, if needed.

transform_syntax_in_macros

Default: false

If true, the following syntax transformations will be permitted inside macros (if the corresponding option has been enabled):

• always_use_return
• annotate_untyped_fields_with_any
• import_to_using
• long_to_short_function_def
• short_circuit_to_if
• short_to_long_function_def

The following syntax transformations will not be permitted inside macros, even if transform_syntax_in_macros is true:

• pipe_to_function_call
• separate_kwargs_with_semicolon

For example, always_use_return does not fire inside a macro by default:

s = """
@macro function f()
    1
end"""

using JuliaFormatter: format_text
format_text(s; always_use_return=true) |> println

@macro function f()
    1
end

However, if transform_syntax_in_macros is set to true, then it does:

format_text(s; always_use_return=true, transform_syntax_in_macros=true) |> println

@macro function f()
    return 1
end

v2_stable_multiline_strings

Default: false

If true, changes the nesting behaviour for multiline strings to guarantee idempotence on formatting.

In general, setting this option to true will cause multiline strings to be indented more to the right; equivalently, setting it to false will cause multiline strings to be shifted onto new lines more easily. However, note that this option is not intended to primarily be used as a way to control indentation of multiline strings. Its primary purpose is to guarantee idempotence; the indentation differences are a side effect which are documented here for users' awareness.

Here is an example of the different output that can be produced by the two settings. This is with the default value of false:

s = """
throw(ArgumentError(\"""
                    ooohhhhhh a very long thing
                    \"""))
"""

using JuliaFormatter: format_text
format_text(s; margin=46, v2_stable_multiline_strings=false) |> println

throw(
    ArgumentError(
        """
        ooohhhhhh a very long thing
        """,
    ),
)

But when v2_stable_multiline_strings is set to true, the output is:

format_text(s; margin=46, v2_stable_multiline_strings=true) |> println

throw(ArgumentError("""
                    ooohhhhhh a very long thing
                    """))

If that description is enough for you, feel free to not read on.

However, a rather long explanation (it is a complicated issue!) is included for the curious reader. Click on the "Show explanation" toggle below to read it.

s = """
foooo((\"""
12345\""", g),
    a, b)
"""

s |> println

foooo(("""
12345""", g),
    a, b)

using JuliaFormatter: format_text
format_text(s; margin=21) |> println

foooo((
    """
12345""",
    g,
), a, b)

format_text(format_text(s; margin=21); margin=21) |> println

foooo(
    (
        """
    12345""",
        g,
    ),
    a,
    b,
)

     """4
000001234
    01234567
   """

s |> println

foooo(("""
12345""", g),
    a, b)

format_text(s; margin=21) |> println

foooo((
    """
12345""",
    g,
), a, b)

format_text(format_text(s; margin=21); margin=21) |> println

foooo(
    (
        """
    12345""",
        g,
    ),
    a,
    b,
)

kw = (margin=21, v2_stable_multiline_strings=true)
format_text(s; kw...) |> println

foooo((
    """
12345""",
    g,
), a, b)

format_text(s; kw...) == format_text(format_text(s; kw...); kw...)

true

s = """
throw(ArgumentError(\"""
                    ooohhhhhh a very long thing
                    \"""))
"""

# multiline string's 'length' is 27, hence over margin
format_text(s; margin=46, v2_stable_multiline_strings=false) |> println

throw(
    ArgumentError(
        """
        ooohhhhhh a very long thing
        """,
    ),
)

# multiline string's 'length' is 3, hence under margin
format_text(s; margin=46, v2_stable_multiline_strings=true) |> println

throw(ArgumentError("""
                    ooohhhhhh a very long thing
                    """))

variable_call_indent

Default: []

The SciMLStyle supports the additional option variable_call_indent. It permits continuation lines in calls to not align with the opening parenthesis.

For example, if variable_call_indent = ["Dict"], the following is allowed:

Dict{Int, Int}(
    1 => 2,
    3 => 4)

(Note that in the configuration, "Dict" must be passed as a string: this is because JuliaFormatter matches it against the name of the function being called.)

If variable_call_indent is empty, the above will be formatted to

Dict{Int, Int}(1 => 2,
    3 => 4)

whitespace_in_kwargs

Default: true

If true, = in keyword arguments will be surrounded by whitespace.

f(; a=4)

to

f(; a = 4)

Note that if this option is false, the arguments on either side of the equals may sometimes be parenthesised to avoid parsing ambiguities. For example, f(s! = x) will be transformed to f((s!)=x), and f(t = >=(1)) will be transformed to f(t=(>=(1))).

whitespace_ops_in_indices

Default: false

If true, whitespace is added for binary operations in indices. Make this true if you prefer arr[a + b] to arr[a+b]. Additionally, if there's a colon : involved, parenthesis will be added to the LHS and RHS.

Example: arr[(i1 + i2):(i3 + i4)] instead of arr[i1+i2:i3+i4].

whitespace_typedefs

Default: false

If true, whitespace is added for type definitions. Make this true if you prefer Union{A <: B, C} to Union{A<:B,C}.

yas_style_nesting

Default: false

The option yas_style_nesting is set to false by default. Setting it to true makes the SciMLStyle use the YASStyle nesting rules. For other styles, this option has no effect.

# With `yas_style_nesting = false`
function my_large_function(argument1, argument2,
    argument3, argument4,
    argument5, x, y, z)
    foo(x) + goo(y)
end

# With `yas_style_nesting = true`
function my_large_function(argument1, argument2,
                           argument3, argument4,
                           argument5, x, y, z)
    foo(x) + goo(y)
end