StyLua

<div align="center"> <h1> StyLua<br> <a href="https://crates.io/crates/stylua"><img src="https://img.shields.io/crates/v/stylua.svg"></a> <a href="https://github.com/JohnnyMorganz/StyLua/actions/workflows/ci.yml"><img src="https://github.com/JohnnyMorganz/StyLua/actions/workflows/ci.yml/badge.svg"></a> <a href="https://codecov.io/gh/JohnnyMorganz/StyLua"><img src="https://codecov.io/gh/JohnnyMorganz/StyLua/branch/main/graph/badge.svg"/></a> </h1> </div>

A deterministic code formatter for Lua 5.1, 5.2, 5.3, 5.4, LuaJIT, Luau and CfxLua/FiveM Lua, built using full-moon. StyLua is inspired by the likes of prettier, it parses your Lua codebase, and prints it back out from scratch, enforcing a consistent code style.

StyLua mainly follows the Roblox Lua Style Guide, with a few deviations.

Installation

There are multiple ways to install StyLua:

With Github Releases

Pre-built binaries are available on the GitHub Releases Page.

By default, these are built with all syntax variants enabled (Lua 5.2, 5.3, 5.4, LuaJIT and Luau), to cover all possible codebases. See configuring runtime syntax selection if you need to select a particular syntax of Lua to format. Alternatively, see installing from crates.io on how to install a particular flavour of StyLua.

From Crates.io

If you have Rust installed, you can install StyLua using cargo. By default, this builds for just Lua 5.1. You can pass the --features <flag> argument to add extra syntax variants:

cargo install stylua
cargo install stylua --features lua52
cargo install stylua --features lua53
cargo install stylua --features lua54
cargo install stylua --features luajit
cargo install stylua --features luau

You can specify multiple features at once, and then use configuration in a .stylua.toml file to defer syntax selection to runtime.

GitHub Actions

The stylua-action GitHub Action can install and run StyLua. This action uses the prebuilt GitHub release binaries, instead of running cargo install, for faster CI startup times.

pre-commit

You can use StyLua with pre-commit. There are 3 possible pre-commit hooks available:

• stylua: installs via cargo - requires the Rust toolchain
• stylua-system: runs a stylua binary available on the PATH. The binary must be pre-installed
• stylua-github: automatically installs the relevant prebuilt binary from GitHub Releases

Add the following to your .pre-commit-config.yaml file:

- repo: https://github.com/JohnnyMorganz/StyLua
  rev: v2.4.0
  hooks:
    - id: stylua # or stylua-system / stylua-github

npm

StyLua is available as a binary published to npm as @johnnymorganz/stylua-bin. This is a thin wrapper that installs the binary and makes it available through npm / npx.

npx @johnnymorganz/stylua-bin --help

StyLua is also available as a WASM library at @johnnymorganz/stylua. It is usable in Node.js, or in the browser (using a bundler).

Docker

StyLua is available on the Docker Hub.

If you are using Docker, the easiest way to install StyLua is:

COPY --from=JohnnyMorganz/StyLua:2.4.0 /stylua /usr/bin/stylua

Homebrew

StyLua is available on macOS via the Homebrew package manager.

brew install stylua

pip / uv

You can install StyLua using pip / uv, by passing in the git repository as the archive URL

pip install git+https://github.com/johnnymorganz/stylua
uv tool install git+https://github.com/johnnymorganz/stylua

Other Installation Methods

• VSCode Extension
• Aftman

aftman add johnnymorganz/stylua@2.4.0

• A community maintained package repository. Please note, these packages are maintained by third-parties and we do not control their packaging manifests.

Other Editor Integrations

Note that these integrations require the StyLua binary to already be installed and available on your system.

• Sublime: Sublime Text Package
• Neovim: stylua-nvim / stylua.nvim
• Zed: Zed Lua StyLua formatter settings

Usage

Once installed, pass the files to format to the CLI:

stylua src/ foo.lua bar.lua

This command will format the foo.lua and bar.lua file, and search down the src directory to format any files within it. StyLua can also read from stdin, by using - as the file name.

Glob Filtering

By default, when searching through a directory, StyLua looks for all files matching the glob **/*.lua (or **/*.luau when luau is enabled) to format. You can also specify an explicit glob pattern to match against when searching:

stylua --glob '**/*.luau' -- src # format all files in src matching **/*.luau
stylua -g '*.lua' -g '!*.spec.lua' -- . # format all Lua files except test files ending with `.spec.lua`

Note that the -g/--glob argument can take multiple strings at once, so -- is required to separate between the glob patterns and the files to format.

By default, glob filtering (and .styluaignore files) are only applied during directory traversal and searching. Files passed directly (e.g. stylua foo.txt) will override the glob / ignore and always be formatted. To disable this behaviour, pass the --respect-ignores flag (stylua --respect-ignores foo.txt).

Filtering using .styluaignore

You can create a .styluaignore file, with a format similar to .gitignore. Any files matching the globs in the ignore file are ignored by StyLua. For example, for a .styluaignore file with the following contents:

vendor/

running stylua . will ignore the vendor/ directory.

Filtering when using stdin

If you are formatting stdin by specifying - as the filename (usually as part of an editor integration) you can optionally provide the filename via --stdin-filepath. To respect glob or .styluaignore filtering, pass --respect-ignores.

stylua --respect-ignores --stdin-filepath src/foo.lua -

--check: Checking files for formatting

To check whether files require formatting (but not write directly to them), use the --check flag. It will take files as input, and output a diff to stdout instead of rewriting the file contents. If there are any files that require formatting, StyLua will exit with status code 1.

There are different styles of output available:

• --output-format=standard: output a custom diff (default)
• --output-format=unified: output a unified diff, consumable by tools like patch or delta
• --output-format=json: output JSON representing the changes, useful for machine-readable output
• --output-format=summary: output a summary list of file paths that are incorrectly formatted

--verify: Verifying formatting output

As a safety measure, you can use the --verify flag to verify the output of all formatting before saving the file.

If enabled, the tool will re-parse the formatted output to verify if the AST is still valid (no syntax errors) and is similar to the input (possible semantic changes).

This is useful when adopting StyLua in a large codebase, where it is difficult to manually check all formatting is correct. Note that this may produce false positives and negatives - we recommend manual verification as well as running tests to confirm.

Ignoring parts of a file

To skip formatting a particular part of a file, you can add -- stylua: ignore before it. This is useful if there is a particular style you want to preseve for readability, e.g.:

-- stylua: ignore
local matrix = {
    { 0, 0, 0 },
    { 0, 0, 0 },
    { 0, 0, 0 },
}

To skip a block of code, use -- stylua: ignore start and -- stylua: ignore end:

local foo = true
-- stylua: ignore start
local   bar   =   false
local  baz      = 0
-- stylua: ignore end
local foobar = false

Note that ignoring cannot cross scope boundaries - once a block is exited, formatting is re-enabled.

Formatting Ranges

To format a specific range within a file, use --range-start <num> and/or --range-end <num>. Both arguments are inclusive and optional - if an argument is not provided, the start/end of the file is used respectively.

Only whole statements lying within the range are formatted. If part of a statement falls outside the range, the statement is ignored.

In editors, Format Selection is supported.

Requires Sorting

StyLua has built-in support for sorting require statements. We group consecutive require statements into a single "block", and then requires are sorted only within that block. Blocks of requires do not move around the file.

StyLua only considers requires of the form local NAME = require(EXPR), and sorts lexicographically based on NAME. (StyLua can also sort Roblox services of the form local NAME = game:GetService(EXPR))

Requires sorting is off by default. To enable it, add the following to your stylua.toml:

[sort_requires]
enabled = true

Language Server