---
name: "ocamlformat"
section: "1"
platform: "linux"
package: "ocamlformat"
version: "0.27.0-1+b6"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/ocamlformat"
---

# ocamlformat(1)

A tool to format OCaml code.

## NAME

ocamlformat - A tool to format OCaml code.

## SYNOPSIS

**ocamlformat** \[*OPTION*\]… \[*SRC*\]…

## DESCRIPTION

**ocamlformat** automatically formats OCaml code.

## OPTIONS (CODE FORMATTING STYLE)

Unless otherwise noted, any option **--***option***=***VAL* detailed in this section can be set in many ways, its value is determined in the following order (of increasing priority): the default value is used if no other value is specified. The value of a boolean option **--foo** or **--no-foo** can be modified in an **.ocamlformat** configuration file with '**foo =** {**true**,**false**}', it can be done for any other option with an '**option =** *VAL*' line (\*), or using the OCAMLFORMAT environment variable: **OCAMLFORMAT=***option***=***VAL***,**...**,***option***=***VAL*, or as an optional parameter on the command line, or with a global **\[@@@ocamlformat "***option***=***VAL***"\]** attribute in the processed file, or with an **\[@@ocamlformat "***option***=***VAL***"\]** attribute on expression in the processed file.

(\*) **.ocamlformat** files in current and all ancestor directories for each input file are used, applied from top to bottom, overriding the settings each time a file is applied, stopping at the project root. If no project root and no **ocamlformat** file has been found, and if the option **enable-outside-detected-project** is set, the global **ocamlformat** file defined in **$XDG\_CONFIG\_HOME** (or in **$HOME/.config** if **$XDG\_CONFIG\_HOME** is undefined) is used.

If the **disable** option is not set, an **.ocamlformat-ignore** file specifies files that OCamlFormat should ignore. Each line in an **.ocamlformat-ignore** file specifies a filename relative to the directory containing the **.ocamlformat-ignore** file. Shell-style regular expressions are supported. Lines starting with **#** are ignored and can be used as comments.

If the **disable** option is set, an **.ocamlformat-enable** file specifies files that OCamlFormat should format even when the **disable** option is set. Each line in an **.ocamlformat-enable** file specifies a filename relative to the directory containing the **.ocamlformat-enable** file. Shell-style regular expressions are supported. Lines starting with **#** are ignored and can be used as comments.

- **--assignment-operator**=*{end-line\|begin-line}*

  Position of the assignment operator. **end-line** positions assignment operators (\`:=\` and \`\<-\`) at the end of the line and breaks after it if the whole assignment expression does not fit on a single line. **begin-line** positions assignment operators (\`:=\` and \`\<-\`) at the beginning of the line and breaks before it if the whole assignment expression does not fit on a single line. The default value is **end-line**.

- **--break-before-in**=*{fit-or-vertical\|auto}*

  Whether the line should break before the *in* keyword of a *let* binding. **fit-or-vertical** will always break the line before the *in* keyword if the whole *let* binding does not fit on a single line. **auto** will only break the line if the *in* keyword does not fit on the previous line. The default value is **fit-or-vertical**.

- **--break-cases**=*{fit\|nested\|toplevel\|fit-or-vertical\|vertical\|all}*

  Break pattern match cases. Specifying **fit** lets pattern matches break at the margin naturally. **nested** forces a break after nested or-patterns to highlight the case body. Note that with **nested**, the **indicate-nested-or-patterns** option is not needed, and so ignored. **toplevel** forces top-level cases (i.e. not nested or-patterns) to break across lines, otherwise break naturally at the margin. **fit-or-vertical** tries to fit all or-patterns on the same line, otherwise breaks. **vertical** vertically breaks branches. **all** forces all pattern matches to break across lines. The default value is **fit**.

- **--break-collection-expressions**=*{fit-or-vertical\|wrap}*

  Break collection expressions (lists and arrays) elements by elements. **fit-or-vertical** vertically breaks expressions if they do not fit on a single line. **wrap** will group simple expressions and try to format them in a single line. The default value is **fit-or-vertical**.

- **--break-colon**=*{after\|before}*

  Break before or after colon in value binding declarations and type constraints. **after** breaks after the colon. **before** breaks before the colon. The default value is **after**.

- **--break-fun-decl**=*{wrap\|fit-or-vertical\|smart}*

  Style for function declarations and types. **wrap** breaks only if necessary. **fit-or-vertical** vertically breaks arguments if they do not fit on a single line. **smart** is like **fit-or-vertical** but try to fit arguments on their line if they fit. The default value is **wrap**.

- **--break-fun-sig**=*{wrap\|fit-or-vertical\|smart}*

  Style for function signatures. **wrap** breaks only if necessary. **fit-or-vertical** vertically breaks arguments if they do not fit on a single line. **smart** is like **fit-or-vertical** but try to fit arguments on their line if they fit. The default value is **wrap**.

- **--break-infix**=*{wrap\|fit-or-vertical\|wrap-or-vertical}*

  Break sequence of infix operators. **wrap** will group simple expressions and try to format them in a single line. **fit-or-vertical** vertically breaks expressions if they do not fit on a single line. **wrap-or-vertical** behaves like **wrap** for high precedence operators and behaves like **fit-or-vertical** for low precedence operators. The default value is **wrap**.

- **--break-infix-before-func**

  Break infix operators whose right arguments are anonymous functions specially: do not break after the operator so that the first line of the function appears docked at the end of line after the operator. The flag is **unset** by default.

- **--break-separators**=*{after\|before}*

  Break before or after separators such as \`;\` in list or record expressions. **after** breaks the expressions after the separator. **before** breaks the expressions before the separator. The default value is **after**.

- **--break-sequences**

  Force sequence expressions to break irrespective of margin. The flag is **set** by default.

- **--break-string-literals**=*{auto\|never}*

  Break string literals. **auto** mode breaks lines at newlines and wraps string literals at the margin. **never** mode formats string literals as they are parsed, in particular, with escape sequences expanded. The default value is **auto**.

- **--break-struct**=*{force\|natural}*

  Break struct-end module items. **force** will break struct-end phrases unconditionally. **natural** will break struct-end phrases naturally at the margin. The default value is **force**.

- **--cases-exp-indent**=*COLS*

  Indentation of cases expressions (*COLS* columns). See also the **cases-matching-exp-indent** and **nested-match** options. The default value is **4**. Cannot be set in attributes.

- **--cases-matching-exp-indent**=*{normal\|compact}*

  Indentation of cases right-hand sides which are \`match\` or \`try\` expressions. **normal** indents as it would any other expression. **compact** forces an indentation of 2, unless **nested-match** is set to **align** and we're on the last case. The default value is **normal**.

- **--disambiguate-non-breaking-match**

  Add parentheses around matching constructs that fit on a single line. The flag is **unset** by default.

- **--doc-comments**=*{after-when-possible\|before-except-val\|before}*

  Doc comments position. **after-when-possible** puts doc comments after the corresponding code. This option has no effect on variant declarations because that would change their meaning and on structures, signatures and objects for readability. **before-except-val** puts doc comments before the corresponding code, but puts doc comments of **val** and **external** declarations after the corresponding declarations. **before** puts comments before the corresponding code. The default value is **after-when-possible**.

- **--doc-comments-padding**=*PADDING*

  Add *PADDING* spaces before doc comments in type declarations. The default value is **2**.

- **--doc-comments-tag-only**=*{default\|fit}*

  Position of doc comments with only tags. **default** means no special treatment. **fit** puts doc comments on the same line. The default value is **default**.

- **--dock-collection-brackets**

  Dock the brackets of lists, arrays and records, so that when the collection does not fit on a single line the brackets are opened on the preceding line and closed on the following line. The flag is **set** by default.

- **--exp-grouping**=*{parens\|preserve}*

  Style of expression grouping. **parens** groups expressions using parentheses. **preserve** preserves the original grouping syntax (parentheses or *begin*/*end*). The default value is **parens**. Cannot be set in attributes.

- **--extension-indent**=*COLS*

  Indentation of items inside extension nodes (*COLS* columns). The default value is **2**.

- **--field-space**=*{loose\|tight\|tight-decl}*

  Whether or not to use a space between a field name and the punctuation symbol (\`:\` or \`=\`) preceding the rhs. This option affects records and objects. **loose** uses a space. **tight** does not use a space. **tight-decl** is **tight** for declarations and **loose** for instantiations. The default value is **loose**.

- **--function-indent**=*COLS*

  Indentation of function cases (*COLS* columns). The default value is **2**.

- **--function-indent-nested**=*{never\|always\|auto}*

  Whether the **function-indent** parameter should be applied even when in a sub-block. **never** only applies **function-indent** if the function block starts a line. **always** always apply **function-indent**. **auto** applies **function-indent** when seen fit. The default value is **never**.

- **--if-then-else**=*{compact\|fit-or-vertical\|vertical\|keyword-first\|k-r}*

  If-then-else formatting. **compact** tries to format an if-then-else expression on a single line. **fit-or-vertical** vertically breaks branches if they do not fit on a single line. **vertical** always vertically breaks branches. **keyword-first** formats if-then-else expressions such that the if-then-else keywords are the first on the line. **k-r** formats if-then-else expressions with parentheses that match the K&R style. The default value is **compact**.

- **--indent-after-in**=*COLS*

  Indentation (*COLS* columns) after \`let ... in\`, unless followed by another \`let\`. The default value is **0**. Cannot be set in attributes.

- **--indicate-multiline-delimiters**=*{no\|space\|closing-on-separate-line}*

  How to indicate that two matching delimiters live on different lines.  **no** doesn't do anything special to indicate the closing delimiter. **space** prints a space inside the delimiter to indicate the matching one is on a different line.  **closing-on-separate-line** makes sure that the closing delimiter is on its own line. The default value is **no**.

- **--indicate-nested-or-patterns**=*{unsafe-no\|space}*

  Control whether or not to indicate nested or-pattern using indentation. **unsafe-no** does not indicate nested or-patterns. Warning: this can produce confusing code where a short body of a match case is visually hidden by surrounding long patterns, leading to misassociation between patterns and body expressions. **space** starts lines of nested or-patterns with " \|" rather than "\| ". The default value is **unsafe-no**.

- **--infix-precedence**=*{indent\|parens}*

  Use indentation or also discretionary parentheses to explicitly disambiguate precedences of infix operators. **indent** uses indentation to explicitly disambiguate precedences of infix operators. **parens** uses parentheses to explicitly disambiguate precedences of infix operators. The default value is **indent**.

- **--leading-nested-match-parens**

  Nested match parens formatting. The flag is **unset** by default. Cannot be set in attributes.

- **--let-and**=*{compact\|sparse}*

  Style of let\_and. **compact** will try to format \`let p = e and p = e\` in a single line. **sparse** will always break between them. The default value is **compact**.

- **--let-binding-deindent-fun**

  Deindent a line beginning with \`fun\`. The flag is **set** by default.

- **--let-binding-indent**=*COLS*

  Indentation of let binding expressions (*COLS* columns) if they do not fit on a single line. The default value is **2**. Cannot be set in attributes.

- **--let-binding-spacing**=*{compact\|sparse\|double-semicolon}*

  Spacing between let binding. **compact** spacing separates adjacent let bindings in a module according to module-item-spacing. **sparse** places two open lines between a multi-line module-level let binding and the next. **double-semicolon** places double semicolons and an open line between a multi-line module-level let binding and the next. The default value is **compact**.

- **--let-module**=*{compact\|sparse}*

  Module binding formatting. **compact** does not break a line after the *let module ... =* and before the *in* if the module declaration does not fit on a single line. **sparse** breaks a line after *let module ... =* and before the *in* if the module declaration does not fit on a single line. The default value is **compact**.

- **--line-endings**=*{lf\|crlf}*

  Line endings used. **lf** uses Unix line endings. **crlf** uses Windows line endings. The default value is **lf**. Cannot be set in attributes.

- **-m** *COLS*, **--margin**=*COLS*

  Format code to fit within *COLS* columns. The default value is **80**. Cannot be set in attributes.

- **--match-indent**=*COLS*

  Indentation of match/try cases (*COLS* columns). The default value is **0**.

- **--match-indent-nested**=*{never\|always\|auto}*

  Whether the **match-indent** parameter should be applied even when in a sub-block. **never** only applies **match-indent** if the match block starts a line. **always** always apply **match-indent**. **auto** applies **match-indent** when seen fit. The default value is **never**.

- **--max-indent**=*COLS*

  Maximum offset (*COLS* columns) added to a new line in addition to the offset of the previous line. The default value is **68**. Cannot be set in attributes.

- **--module-item-spacing**=*{compact\|sparse\|preserve}*

  Spacing between items of structures and signatures. **compact** will not leave open lines between one-liners of similar sorts. **sparse** will always break a line between two items. **preserve** will not leave open lines between one-liners of similar sorts unless there is an open line in the input. The default value is **compact**.

- **--nested-match**=*{wrap\|align}*

  Style of a pattern-matching nested in the last case of another pattern-matching. **wrap** wraps the nested pattern-matching with parentheses and adds indentation. **align** vertically aligns the nested pattern-matching under the encompassing pattern-matching. The default value is **wrap**.

- **--no-break-infix-before-func**

  Unset **break-infix-before-func**.

- **--no-break-sequences**

  Unset **break-sequences**.

- **--no-disambiguate-non-breaking-match**

  Unset **disambiguate-non-breaking-match**.

- **--no-dock-collection-brackets**

  Unset **dock-collection-brackets**.

- **--no-leading-nested-match-parens**

  Unset **leading-nested-match-parens**.

- **--no-let-binding-deindent-fun**

  Unset **let-binding-deindent-fun**.

- **--no-ocp-indent-compat**

  Unset **ocp-indent-compat**.

- **--no-parens-ite**

  Unset **parens-ite**.

- **--no-parse-docstrings**

  Unset **parse-docstrings**.

- **--no-parse-toplevel-phrases**

  Unset **parse-toplevel-phrases**.

- **--no-space-around-arrays**

  Unset **space-around-arrays**.

- **--no-space-around-lists**

  Unset **space-around-lists**.

- **--no-space-around-records**

  Unset **space-around-records**.

- **--no-space-around-variants**

  Unset **space-around-variants**.

- **--no-wrap-comments**

  Unset **wrap-comments**.

- **--no-wrap-fun-args**

  Unset **wrap-fun-args**.

- **--ocp-indent-compat**

  Attempt to generate output which does not change (much) when post-processing with ocp-indent. The flag is **unset** by default.

- **-p** *{default\|conventional\|ocamlformat\|janestreet}*, **--profile**=*{default\|conventional\|ocamlformat\|janestreet}*

  Select a preset profile which sets *all* options, overriding lower priority configuration. **default** is an alias for the **conventional** profile. The **conventional** profile aims to be as familiar and "conventional" appearing as the available options allow. The **ocamlformat** profile aims to take advantage of the strengths of a parsetree-based auto-formatter, and to limit the consequences of the weaknesses imposed by the current implementation. This is a style which optimizes for what the formatter can do best, rather than to match the style of any existing code. General guidelines that have directed the design include: Legibility, in the sense of making it as hard as possible for quick visual parsing to give the wrong interpretation, is of highest priority; Whenever possible the high-level structure of the code should be obvious by looking only at the left margin, in particular, it should not be necessary to visually jump from left to right hunting for critical keywords, tokens, etc; All else equal compact code is preferred as reading without scrolling is easier, so indentation or white space is avoided unless it helps legibility; Attention has been given to making some syntactic gotchas visually obvious. The **janestreet** profile is used at Jane Street. The default value is **default**.

- **--parens-ite**

  Uses parentheses around if-then-else branches that spread across multiple lines. The flag is **unset** by default.

- **--parens-tuple**=*{always\|multi-line-only}*

  Parens tuple expressions. **always** always uses parentheses around tuples. **multi-line-only** mode will try to skip parens for single-line tuples. The default value is **always**.

- **--parens-tuple-patterns**=*{multi-line-only\|always}*

  Parens tuple patterns. **multi-line-only** mode will try to skip parens for single-line tuple patterns. **always** always uses parentheses around tuples patterns. The default value is **multi-line-only**.

- **--parse-docstrings**

  Parse and format docstrings. The flag is **set** by default.

- **--parse-toplevel-phrases**

  Parse and format toplevel phrases and their output. The flag is **unset** by default.

- **--sequence-blank-line**=*{preserve-one\|compact}*

  Blank line between expressions of a sequence. **preserve** will keep a blank line between two expressions of a sequence if the input contains at least one. **compact** will not keep any blank line between expressions of a sequence. The default value is **preserve-one**.

- **--sequence-style**=*{terminator\|separator\|before}*

  Style of sequence. **terminator** only puts spaces after semicolons. **separator** puts spaces before and after semicolons. **before** breaks the sequence before semicolons. The default value is **terminator**.

- **--single-case**=*{compact\|sparse}*

  Style of pattern matching expressions with only a single case. **compact** will try to format a single case on a single line. **sparse** will always break the line before a single case. The default value is **compact**.

- **--space-around-arrays**

  Add a space inside the delimiters of arrays. The flag is **set** by default.

- **--space-around-lists**

  Add a space inside the delimiters of lists. The flag is **set** by default.

- **--space-around-records**

  Add a space inside the delimiters of records. The flag is **set** by default.

- **--space-around-variants**

  Add a space inside the delimiters of variants. The flag is **set** by default.

- **--stritem-extension-indent**=*COLS*

  Indentation of structure items inside extension nodes (*COLS* columns). The default value is **0**.

- **--type-decl**=*{compact\|sparse}*

  Style of type declaration. **compact** will try to format constructors and records definition in a single line. **sparse** will always break between constructors and record fields. The default value is **compact**.

- **--type-decl-indent**=*COLS*

  Indentation of type declarations (*COLS* columns) if they do not fit on a single line. The default value is **2**. Cannot be set in attributes.

- **--wrap-comments**

  Comments are divided into paragraphs by open lines (two or more consecutive newlines), and each paragraph is wrapped at the margin. Multi-line comments with vertically-aligned asterisks on the left margin are not wrapped. Consecutive comments with both left and right margin aligned are not wrapped either. The flag is **unset** by default.

- **--wrap-fun-args**

  Style for function call. The flag is **set** by default.

## OPTIONS (REMOVED)

- **--align-cases**=*VAL*

  This option has been removed in version 0.22.

- **--align-constructors-decl**=*VAL*

  This option has been removed in version 0.22.

- **--align-variants-decl**=*VAL*

  This option has been removed in version 0.22.

- **--doc-comments-val**=*VAL*

  This option has been removed in version 0.16. If you are using \`doc-comments-val=before\` in combination with \`doc-comments=before\` then only \`doc-comments=before\` is now required to achive the same behavior. If you are using \`doc-comments-val=before\` in combination with \`doc-comments=after\` this behavior is not available anymore. If you are using \`doc-comments-val=after\` in combination with \`doc-comments=before\` please now use \`doc-comments=before-except-val\`. If you are using \`doc-comments-val=after\` in combination with \`doc-comments=after\` then only \`doc-comments=after-when-possible\` is now required to achieve the same behavior. If you are using \`doc-comments-val=unset\` the same behavior can now be achieved by setting \`doc-comments\` only.

- **--escape-chars**=*VAL*

  This option has been removed in version 0.16. Concrete syntax will now always be preserved.

- **--escape-strings**=*VAL*

  This option has been removed in version 0.16. Concrete syntax will now always be preserved.

- **--extension-sugar**=*VAL*

  This option has been removed in version 0.17. Concrete syntax will now always be preserved.

- **--let-open**=*VAL*

  This option has been removed in version 0.17. Concrete syntax will now always be preserved.

## OPTIONS

Unless mentioned otherwise non-formatting options cannot be set in attributes or **.ocamlformat** files.

- **-c** *VAL*, **--config**=*VAL* (absent **OCAMLFORMAT** env)

  Aggregate options. Options are specified as a comma-separated list of pairs: *option***=***VAL***,**...**,***option***=***VAL*.

- **--check**

  Check whether the input files already are formatted. Mutually exclusive with --inplace and --output.

- **--comment-check**

  Control whether to check comments and documentation comments. Unsafe to turn off. May be set in **.ocamlformat**. The flag is **set** by default.

- **--disable**

  Disable ocamlformat. This is used in attributes to locally disable automatic code formatting. One can also use **\[@@@ocamlformat "enable"\]** instead of **\[@@@ocamlformat "disable=false"\]**. The flag is **unset** by default.

- **--disable-conf-attrs**

  Disable configuration in attributes. The flag is **unset** by default.

- **--disable-conf-files**

  Disable .ocamlformat configuration files.

- **--disable-outside-detected-project**

  If no **.ocamlformat** config files have been detected, disable the formatting. OCamlFormat is disabled outside of a detected project by default, to enable the opposite behavior use **--enable-outside-detected-project**.

- **--doc**

  Parse input as an odoc documentation.

- **--enable-outside-detected-project**

  Read **.ocamlformat** config files outside the current project when no project root has been detected for the input file. The project root of an input file is taken to be the nearest ancestor directory that contains a **.git** or **.hg** or **dune-project** file. If **.ocamlformat** config files are located in the same directory or parents they are applied, if no **.ocamlformat** file is found then the global configuration defined in **$XDG\_CONFIG\_HOME/.ocamlformat** (or in **$HOME/.config/.ocamlformat** if **$XDG\_CONFIG\_HOME** is undefined) is applied.

- **-g**, **--debug**

  Generate debugging output. The flag is **unset** by default.

- **-i**, **--inplace**

  Format in-place, overwriting input file(s).

- **--ignore-invalid-option**

  Ignore invalid options (e.g. in .ocamlformat).

- **--impl**

  Parse input as an implementation.

- **--intf**

  Parse input as an interface.

- **--margin-check**

  Emit a warning if the formatted output exceeds the margin. The flag is **unset** by default.

- **-n** *N*, **--max-iters**=*N*

  Fail if output of formatting does not stabilize within *N* iterations. May be set in **.ocamlformat**. The default value is **10**.

- **--name**=*NAME*

  Name of input file for use in error reporting and starting point when searching for '.ocamlformat' files. Defaults to the input file name. Some options can be specified in configuration files named '.ocamlformat' in the same or a parent directory of *NAME*, see documentation of other options for details.

- **--no-comment-check**

  Unset **comment-check**.

- **--no-debug**

  Unset **debug**.

- **--no-disable**

  Unset **disable**.

- **--no-disable-conf-attrs**

  Unset **disable-conf-attrs**.

- **--no-margin-check**

  Unset **margin-check**.

- **--no-quiet**

  Unset **quiet**.

- **--no-version-check**

  Unset **version-check**.

- **-o** *DST*, **--output**=*DST*

  Output file. Mutually exclusive with --inplace. Write to stdout if omitted.

- **--ocaml-version**=*V*

  Version of OCaml syntax of the output. The default value is **4.04.0**.

- **--ocp-indent-config**

  Read .ocp-indent configuration files. **base** is an alias for **let-binding-indent**. **type** is an alias for **type-decl-indent**. **in** is an alias for **indent-after-in**. **with** sets **function-indent** and **match-indent**. **match\_clause** is an alias for **cases-exp-indent**. **ppx\_stritem\_ext** is an alias for **stritem-extension-indent**. **max\_indent** is an alias for **max-indent**. **strict\_with** sets **function-indent-nested** and **match-indent-nested**.

- **--print-config**

  Print the configuration determined by the environment variable, the configuration files, preset profiles and command line. Attributes are not considered. If many input files are specified, only print the configuration for the first file. If no input file is specified, print the configuration for the root directory if specified, or for the current working directory otherwise.

- **-q**, **--quiet**

  Quiet. May be set in **.ocamlformat**. The flag is **unset** by default.

- **--repl-file**

  Parse input as toplevel phrases with their output.

- **--root**=*DIR*

  Root of the project. If specified, only take into account .ocamlformat configuration files inside *DIR* and its subdirectories.

- **--use-file**

  Deprecated. Same as **impl**.

- **--version-check**

  Check that the version matches the one specified in .ocamlformat. The flag is **set** by default.

- *SRC*

  Input files. At least one is required, and exactly one without **--inplace**. If **-** is passed, will read from stdin.

## COMMON OPTIONS

- **--help**\[=*FMT*\] (default=**auto**)

  Show this help in format *FMT*. The value *FMT* must be one of **auto**, **pager**, **groff** or **plain**. With **auto**, the format is **pager** or **plain** whenever the **TERM** env var is **dumb** or undefined.

- **--version**

  Show version information.

## EXIT STATUS

**ocamlformat** exits with:

- 0

  on success.

- 123

  on indiscriminate errors reported on standard error.

- 124

  on command line parsing errors.

- 125

  on unexpected internal errors (bugs).

## ENVIRONMENT

These environment variables affect the execution of **ocamlformat**:

- **OCAMLFORMAT**

  See option **--config**.