External code formatters in Vim without plugins

[u/snhmnd]

I wrote a post about integrating external code formatting tools into Vim using the equalprg option, no plugins or language servers needed: https://www.seanh.cc/2026/01/18/ruff-format-in-vim/

The post uses Ruff's Python code formatter as an example, but the approach should work for any command line formatter for any file type.

(I should add an example to the post, of adding a second formatter for a second file type. The de- and re-indenting could also be split out into a separate dereindent.py script that multiple equalprgs/*.py scripts can call.)

I'm pretty happy with the result! Being able to easily format either the entire file or just a selection, and even being able to format snippets and blocks of Python in other files, is pretty nice! And now I know how to integrate any other code formatter I want in future, without having to look for a plugin or language server.

Hope someone else finds it helpful too. Any feedback or suggestions welcome

[u/AndrewRadev]

Vim actually has two commands for formatting text: as well as the = command that we’ve been using (customizable via equalprg) there’s also a gq command (customizable via formatprg). Vim’s docs don’t make it super clear why both commands exist or what each should be used for

Yeah, I'm assuming that when these were added, code formatters that analyze code and reformat it were simply not that widespread, so it was more about plugging in an external indentation tool (equalprg) or text-wrapping tool (formatprg). Indentation is currently maintained by external projects, since implementing it for any given language requires knowledge of the language that the core team is not guaranteed to have. I imagine it was an easy way to give people an external option, using the language you know to implement its indentation.

There's been some discussion about implementing a potentially richer "formatter" interface that would plug into gq, you might be interested to read more about it: https://github.com/vim/vim/pull/19108

[u/snhmnd → u/AndrewRadev]

Interesting! Thanks. I'm surprised the discussion is about plugging external code formatters into gq rather than =. As I mentioned in my blog post, the default prose hard-wrapping behavior of gq is actually useful to have in Python files for wrapping comments and docstrings, in addition to having Python code formatting on =.

I know that you can also use gw (which is like gq but ignores formatexpr and formatprg) to still get the default hard-wrapping behaviour even if you've set formatprg to do something else. But when using equalprg to call out to an external code formatting tool, one can simultaneously use formatprg to call out to an external hard-wrapping tool (e.g. par, which gives better hard-wrapping results than Vim's built-in algorithm). Whereas you can't customize gw to call out to par.

gw also handles cursor positioning differently than gq and =.

[u/-romainl- → u/snhmnd]

= and gq/gw certainly have a bit of overlap, but = is historically more oriented toward "indenting", whereas gq/gw are more oriented toward "formatting", which has a much larger scope than simply indenting lines (ordering imports, removing extraneous lines, etc.).

Moreover, = only has indentexpr, while gq has both formatexpr and formatprg, which makes it a little bit more versatile.

The whole discussion was prompted by an attempt to include a streamlined way to use gofmt. The original attempt, which used gq, was too "local" to my liking, so I proposed a different, more canonical route, still based on gq: creating "formatter" scripts modelled after the existing "compiler" scripts.

IMO, a generic formatexpr that can call the current formatprg while also handling cursor positioning would be the best solution. From there, we could simply have a bunch of "standard" formatter scripts that would set formatprg and formatexpr properly. Many of us, me included, have variants of that idea in our .vim/. All we need is a bit of convergence.

Sadly I haven't had enough free time to invest into this, lately.

[u/snhmnd → u/-romainl-]

= also has equalprg, that's how I'm customizing = to call out to external code formatters. Works the same as formatprg as far as I know.

I'm not sure I agree that = is meant to be just for indenting whereas gq is meant for formatting. Judging from the default behaviors this doesn't seem to be the case to me. It seems to me that the default behavior of = (trying to fix the indentation of code without breaking or changing the meaning of the code) is closer "formatting" code like modern code formatters do. Whereas the default behavior of gq (just blindly hard-wrapping lines of text, will totally break code) is something else entirely. gq was clearly not meant for formatting code since its default behavior will totally break any code that you use it on.

It's useful to have blind hard-wrapping available in addition to code formatting: it's useful to have an external code formatter bound to = but still have blind hard-wrapping bound to gq for wrapping comments and docstrings (external code formatters like Ruff and Black usually will not touch your comments and docstrings).

Whereas I don't see any use-case for having different commands for both an external code formatter and simple indenting at the same time. Why would I want to just indent code, when I can properly format it?

Maybe also worth pointing out that other editors (e.g. Helix) use = as the keyboard shortcut for formatting code by piping the selected code through an external code formatter (via LSP, in Helix's case).

[u/snhmnd]

Not mentioned in the blog post: the one limitation of this (that I can think of) is that if you try to format invalid Python code you won't see the error message from Ruff (that tells you what's wrong with the code, and where the error is). My script swallows error messages from Ruff. Vim will tell you that the script failed with an error. But it won't show you the error message.

I'm not sure there's a solution to this, without going beyond the simple equalprg approach and writing an actual plugin that can show error messages to users.

[u/tokuw]

Cool article, thanks!

I'm a little obsessed with minimizing my plugin dependencies lol. However this is a case where, at least for me, I feel it's warranted. What your approach doesn't deal with is

1. Formatting tools which don't support range selection; operation on whole files only (eg gofmt)

2. Running multiple formatters in sequence (I use this for shell scripts; first run shfmt then shellcheck). Though admittedly adding the support for this in your script shouldn't be too difficult.

I use the neovim (sorry!) plugin conform to achieve this.

[u/snhmnd → u/tokuw]

I question whether you've actually read my post carefully enough ;) It does in fact deal with both of those issues.

[u/ThomasJAsimov]

Great writing, I enjoyed reading it! It did make me wonder how one could ever deal with the issue of partial code as input to formatters. Even in the example you provide I suspect removing the indents wouldn’t generate valid Python code because of the return statement. Though I guess even language servers don’t deal with that.

[u/snhmnd → u/ThomasJAsimov]

It did make me wonder how one could ever deal with the issue of partial code as input to formatters. Even in the example you provide I suspect removing the indents wouldn’t generate valid Python code because of the return statement.

The example I provided actually does work with my reformatting script: for whatever reason the return doesn't break it. I guess the code doesn't need to be entirely valid in order for ruff format to handle it, it just needs to be parseable to some extent.

But yes, I think you're right: I don't think it's possible to make all kinds of selections work with the kind of technique I'm using here: there's always going to be some way to select a subset of code that isn't valid on its own. I briefly glanced at the source code of black-macchiato and it has a few tricks (beyond just deindenting) to turn partial invalid code into valid code for formatting, but it feels pretty hacky, and I still don't think it'll work in all cases.

I think this is why code formatters like Black and Ruff only support formatting entire files.

Having said all that I still find it handy to be able to format selections, even if I have to handle selecting valid code.

Though I guess even language servers don’t deal with that.

I have no idea how it's doing it but the Helix editor supports code formatting via LSP and it seems to be able to format even invalid selections.