iron.nvim: A REPL Plugin and Library That Stays Out of Your Work Buffer

What iron.nvim Actually Solves

Most Neovim REPL plugins force you to split your window and then manually switch focus, or they send code to a terminal that is hidden from view. iron.nvim takes a different route: it lets you send lines or blocks to a REPL process that lives in a separate window, either a split or a floating window, while you stay in your work buffer. The README states that Iron allows you to quickly interact with the repl without having to leave your work buffer. That is the core problem: keeping your editing context intact while evaluating code. It is for developers who live in Neovim and want a REPL for languages like Python, shell, or Haskell, without reaching for a terminal emulator or a second editor window.

Plugin and Library: Two Layers in One

Iron is not just a set of commands. The README explicitly says it is both a plugin and a library. The plugin layer gives you the setup function and the repl_definition table. The library layer exposes modules like iron.core, iron.view, and iron.fts.common, which you can call from your own Lua code. That split means you can either use the defaults or build custom behavior on top. The library aspect is what makes it extensible: you can define a REPL command as a function that receives a meta table, giving you access to the current buffer name or number. For example, the Haskell definition in the README uses a function to build a cabal v2-repl command that loads the current file. That is a real programmatic hook, not just a static command string.

How the Configuration Works: Commands and Formats

The configuration is done through iron.setup with a config table. The key is repl_definition, a dictionary mapping filetypes to a table with at least a command field. The command can be a simple list like { "python3" } or a function returning a list. For Python, the README shows how to add a format field, common.bracketed_paste_python, and block_dividers like { "# %%", "#%%" }. Those block dividers are how iron decides what counts as a block for sending code in chunks. The format field likely handles bracketed paste mode, which is common in Python REPLs to avoid indentation issues. If you want a custom REPL that loads the current file, you write a command function that reads vim.api.nvim_buf_get_name(meta.current_bufnr). That is a concrete, documented example of the function form.

Window Management: Splits and Floats with a Fluent API

Iron gives you two ways to open a REPL window: splits and floats. For splits, you can set repl_open_cmd to a string like "vertical botright 80 split", or use the view module's fluent API. The README mentions a metatable that lets you chain arguments like vertical, leftabove, rightbelow, topleft, botright. That is a clever design: you write the same tokens you would in a Vim command, but in Lua. For floats, you use view.top("10%") or view.center("30%", 20). The center function takes one or two arguments, and if you give a function, it is called twice, once for width and once for height. That lets you size the float dynamically based on the editor's orientation. The README shows a function that returns 50 for vertical and 20 for horizontal. This is a flexible system, but it is also where the documentation starts to feel thin: the README cuts off mid-sentence in the split section, so you have to guess at the full API.

A Genuine Limitation: Configuration Burden and Thin Docs

Iron is not a plug-and-play plugin. The README gives you a minimal Python and shell setup, but for any other language you must write your own repl_definition. That includes knowing the exact command for your REPL, whether it needs a format function, and what block dividers to use. The documentation is truncated in the README, especially around the split API, and there is no mention of keybindings or default mappings. If you want to send a line to the REPL, you have to figure out which function to call, because the README does not list the core API functions like iron.core.send. That is a real barrier. For a user who just wants to press a key and evaluate code, iron will feel like a puzzle. The library approach gives power, but it sacrifices out-of-the-box usability.

When Iron Is the Wrong Tool

Iron is the wrong choice if you need a REPL that works with minimal setup across many languages. The README only shows definitions for sh, python, and haskell. For anything else, you are on your own. Also, if you prefer a terminal buffer that you can interact with directly, iron's model of sending code to a background process might feel indirect. The scratch_repl option is mentioned, but its semantics are not explained beyond "whether a repl should be discarded or not." If you want a REPL that you can manually type into, a plain :terminal split in Neovim might be simpler. Iron is also not ideal for languages where the REPL is not line-oriented, like some compiled languages, because the send mechanism likely relies on newline-terminated input.

Alternatives: Conjure and vim-fireplace

A close alternative is Conjure, which is a Neovim plugin for interactive evaluation, but it focuses on Clojure and Lisp dialects. Conjure has a more opinionated user experience: it automatically connects to a running process and provides keybindings out of the box. Iron is language-agnostic, so you define the command yourself. Another alternative is vim-fireplace, which is for Clojure only and uses a different transport: it talks to a running nREPL server over a socket, not a terminal REPL. That means vim-fireplace gives you structured responses and error handling, while iron sends raw text to a terminal. If you work in Clojure, Conjure or fireplace will be more ergonomic. If you work in Python or shell, iron's terminal-based approach is simpler and does not require a special server.

Maintenance and License

The repository is under the BSD-3-Clause license, which is permissive and allows commercial use with attribution. That is a low-risk license for adoption. However, the repository metadata shows no recent releases and no last push date, and the default branch is master. The README is the only substantial documentation, and it is truncated. That suggests the project may be in a maintenance lull. The code is written in Lua, so it integrates natively with Neovim, but any upgrade cost depends on how the API changes if the project resumes active development. Since there are no release notes, you cannot know what changed between commits. Before adopting, you should check the commit history on GitHub to see if issues are being addressed. The lack of a release tag is a warning sign for a library that you might build on.

Editorial conclusion

Adopt iron.nvim if you write code in multiple languages, want a REPL that does not hijack your main buffer, and are comfortable writing Lua configuration. Skip it if you prefer a batteries-included plugin with a graphical menu or if you need a stable, documented API. Before committing, verify that your language's REPL works with the command table or function form, test the float sizing callbacks in your Neovim version, and check whether the project is still actively maintained, since the repository shows no recent releases or push data.

Official sources

1. Official README
2. Project repository