latexindent.pl

latexindent.pl is a perl script to beautify/tidy/format/indent (add horizontal leading space to) code within environments, commands, after headings and within special code blocks.

It has the ability to align delimiters in environments and commands, and can modify line breaks including text wrapping and one-sentence-per-line.

It can also perform string-based and regex-based substitutions/replacements. The script is customisable through its YAML interface.

It has support for Conda, docker and pre-commit.

version

latexindent.pl, version 4.0, 2026-03-15

author

Chris Hughes (cmhughes)

example

Before:

\begin{one}
latexindent.pl adds leading
space to code blocks.
\begin{two}
It aims to beautify .tex, .sty
and .cls files. It is customisable
via its YAML interface.
\end{two}
\end{one}

After running

latexindent.pl myfile.tex

then you receive:

\begin{one}
	latexindent.pl adds leading
	space to code blocks.
	\begin{two}
		It aims to beautify .tex, .sty
		and .cls files. It is customisable
		via its YAML interface.
	\end{two}
\end{one}

tl;dr, a quick start section is available for those short of time.

There are many more features available, detailed in full within the documentation.

documentation

For complete details, please see:

pdf: http://mirrors.ctan.org/support/latexindent/documentation/latexindent.pdf
online: http://latexindentpl.readthedocs.io/ (if you find discrepancies between the pdf and readthedocs, defer to the pdf)

getting started

<details> <summary>perl users</summary>

You'll need

latexindent.pl
LatexIndent/*.pm
defaultSettings.yaml

in the same directory.

You'll need a few readily-available perl modules. Full details are given within the Appendix of the documentation; you might also like to see .appveyor.yml for Strawberry perl users.

</details> <details> <summary>Windows users without perl</summary> Windows users who do not have a perl installation might prefer to get

latexindent.exe

latexindent.exe is a standalone executable file which does not require a perl installation. It is available at releases page of this repository and also from https://ctan.org/tex-archive/support/latexindent.

</details> <details> <summary>Linux users</summary>

Please see the Linux section of the appendix

</details> <details> <summary>Ubuntu Linux users without perl</summary> Ubuntu Linux users who do not have a perl installation might try the standalone executable

latexindent-linux

which should be saved as simply latexindent. It is available at releases page of this repository and also from https://ctan.org/tex-archive/support/latexindent.

</details> <details> <summary>Mac users</summary>

Please see the Mac section of the appendix

</details> <details> <summary>Mac users without perl</summary> Mac users who do not have a perl installation might try the standalone executable

latexindent-macos

which should be saved as simply latexindent. It is available at releases page of this repository and also from https://ctan.org/tex-archive/support/latexindent.

</details> <details> <summary>conda users</summary> If you use conda you'll only need

conda install latexindent.pl -c conda-forge

this will install the executable and all its dependencies (including perl) in the activate environment. You don't even have to worry about defaultSettings.yaml as it is included too.

Full details at using conda.

Important: the executable name is latexindent.pl (not latexindent).

</details> <details> <summary>docker users</summary> If you use latexindent via docker you'll only need

docker pull ghcr.io/cmhughes/latexindent.pl
docker run -v /path/to/local/myfile.tex:/myfile.tex --rm -it ghcr.io/cmhughes/latexindent.pl -s -w myfile.tex

Full details at using docker.

</details>

pre-commit

You can use latexindent with the pre-commit framework by adding this to your .pre-commit-config.yaml:

  - repo: https://github.com/cmhughes/latexindent.pl.git
    rev: V4.0
    hooks:
      - id: latexindent

Full details at pre-commit users, including a worked example demonstrating how you can add a .latexindent.yaml to the root of the git repo to customize the behavior.

testing

A nice way to test the script is to navigate to the test-cases directory, and then run the command (on Linux/Mac -- sorry, a Windows test-case version is not available):

./test-cases.sh

GitHub codespaces

This repository contains a vscode devcontainer configuration that allows developing and testing with GitHub codespaces or vscode devcontainers.

Using GitHub codespaces allows developing in a remote virtual container running vscode with a preconfigured perl installation. You can explore this by clicking on the Code dropdown at the top of this repository, and click on 'Codespaces'; see the codespaces details and screenshots for more information.

important

This script may not work for your style of formatting; I highly recommend that when you first use the script you use the -o switch to output to a separate file; something like

latexindent.pl myfile.tex -o myfile-output.tex

and then check myfile-output.tex carefully to make sure that nothing has been changed (or removed) in a way that will damage your file.

I recommend using each of the following:

a visual check, at the very least;
a check using latexdiff myfile.tex myfile-output.tex.

I recommend using a version control system to track your files, especially if you intend to use latexindent.pl to modify files.

feature requests

I'm happy to review feature requests, but I make no promises as to if they will be implemented; if they can be implemented, I make no promises as to how long it will take to implement them, and in which order I do so -- some features are more difficult than others! Feel free to post on the issues page of this repository, but please do use the given issue template!

development model

I follow the development model given here: http://nvie.com/posts/a-successful-git-branching-model/ which means that latexindent.pl always has (at least) two branches:

main
develop

The main branch always contains the released version and develop contains the development version. When developing a new feature or bug fix, I typically use:

git checkout develop
git checkout -b feature/name-of-feature

and then I merge it into the develop branch using

git checkout develop
git merge feature/name-of-feature --no-ff

I align with many of the approaches and details at Dramatically increase your productivity with Atomic Git Commits.

perl version

I develop latexindent.pl on Ubuntu Linux, using perlbrew; I currently develop on perl version v5.42.0

GitHub Actions

The standalone executables latexindent.exe, latexindent-linux, latexindent-macos are created and released by GitHub Actions; the file that controls this is available within the [github/workflows](http

Latexindent.pl

Install / Use

README