# nREPL is the network REPL protocol Clojure tooling builds on

> nREPL is a Clojure network REPL that ships a server, a client and a set of common APIs used by IDEs and other tools to evaluate Clojure code remotely. Its protocol is formally specified and its maintainers pledge to change it only in backwards-compatible ways, which is what makes it a dependency rather than a tool of convenience.

**nrepl/nrepl** — A Clojure network REPL that provides a server and client, along with some common APIs of use to IDEs and other tools that may need to evaluate Clojure code in remote environments.

- Repository: https://github.com/nrepl/nrepl
- Website: https://nrepl.org
- Stars: 908 · Forks: 111
- Language: Clojure
- License: not declared
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/nrepl-nrepl

## A network REPL is an API that happens to evaluate code

nREPL is a Clojure network REPL: a REPL server, a REPL client, and a set of common APIs that IDEs and other tools use to evaluate Clojure code in remote environments. The description matters more than it first looks. The thing being standardised is not a terminal session, it is a set of operations over a connection, and the ecosystem of editors that build on it is a set of clients of that protocol.

The documented usage is three steps. Start an nREPL server, for example with lein repl. Connect to the server with any nREPL client, and the documentation names CIDER, Calva, vim-fireplace and rebel-readline as examples. Then work. The server side is a background process that stays alive while you evaluate expressions against it, and the client side is the part your editor talks to.

That split is the design decision worth noting. Because the client and the server are separated by a network protocol, the environment where code is evaluated does not have to be the environment where the editor runs, and the person editing code does not have to be the person who started the process. Everything else in this project follows from that one decision.

The audience is the people who write those tools. The project documentation states that nREPL powers many well-known development tools, and the API documentation is published on cljdoc for the current version. A tool author is the typical user, not an end user of an editor.

## The spec at spec.nrepl.org is the actual product

The status section of the project is unusually blunt. It calls itself extremely stable, says the protocol and API are rock-solid and battle tested, and states that the team pledges to evolve them only in backwards-compatible ways. The protocol itself is formally specified at spec.nrepl.org, separate from the implementation.

For a reader deciding whether to build on nREPL, that separation is the whole answer. A REPL protocol that lives only in one implementation's source code cannot be depended upon by third party tools, because a refactor in that codebase is a breaking change for every editor in the ecosystem. A protocol that has its own specification document can be implemented independently, and the project says as much in its own words: implementing new nREPL servers is pretty simple.

The middle ground is experimental features. The documentation states that all experimental features are marked explicitly as such, and adds that even those are fairly stable by most standards. This is the honest caveat to the stability claim. The protocol is stable, and the parts labelled experimental are the parts where a change is permitted. A tool that depends only on stable operations has a long life ahead of it; a tool that leans on the experimental set is accepting a different contract, and the marking is what lets you know which one you are in.

The middlewares are the extension mechanism, and their descriptors are generated from the code rather than written by hand. The Makefile has a docs target that regenerates doc/modules/ROOT/pages/ops.adoc and a verify-docs target that fails the build if the generated file differs from the committed one, with the comment explaining that this catches cases where middleware descriptors changed but the generated documentation was not regenerated or was edited by hand. The middleware contract is therefore kept in sync by the build, not by discipline.

## Starting a server and attaching a client

There is no elaborate setup in the documentation, which is itself a fact about how the tool is used. The whole procedure for a standard workflow is:

```bash
lein repl
```

That starts a server. Any nREPL client then connects to it, and the documentation names CIDER for Emacs, Calva for VS Code, vim-fireplace for Vim and rebel-readline as a terminal client. Clients are interchangeable because they speak the protocol rather than a particular implementation's internals.

For a ClojureScript project, the reference implementation is not enough on its own. The project states that the reference nREPL implementation is Clojure-specific, and that ClojureScript support is added by extending it with the Piggieback middleware. The FAQ is explicit that the answer here is yes and no. The protocol can carry ClojureScript evaluation, but the Clojure reference server does not do it out of the box, and the documentation notes that in the future there may be implementations of nREPL that target ClojureScript directly.

That distinction is easy to miss and it decides whether nREPL is a dependency or a detour for a given team. If your editor integration evaluates Clojure in a JVM process, nREPL is the thing to build on. If it evaluates ClojureScript, you are depending on a middleware from another project and on the reference server behaving well under it, and that is a different risk profile from the one the stability pledge covers.

The protocol side is broader than Clojure. The project states that the nREPL protocol is language-agnostic and that implementations of nREPL servers exist for several programming languages, with the list kept on the site. So a tool that speaks nREPL can talk to a server that is not this one, which is a stronger guarantee than the language specific implementation alone.

## Building and testing nREPL from its own repository

The repository is laid out for contributors, and the Makefile shows the workflow. The default goal is install, and the toolchain is driven by deps.edn with a build alias. Compilation of the Java sources happens through the build alias:

```bash
clojure -T:build javac
```

The test target depends on a compilation step that includes the tests, and then runs the suite through an alias keyed on the Clojure version:

```bash
clojure -M:$(CLOJURE_VERSION):dev:test$(EXTRA_ALIASES)
```

The Clojure version variable defaults to 1.12, so the default run exercises a recent Clojure release, and the EXTRA_ALIASES hook lets you add extra alias sets without editing the target. Linting is split into three separate tools, each with its own target, which are then combined:

```bash
clojure -M:kondo
```

That is clj-kondo, and it sits alongside a cljfmt check and the Eastwood linter in the lint target. Eastwood is run with an extra alias for junixsocket, which is a detail that only matters if you are contributing to the socket handling code. Coverage is measured with cloverage through its own target, and the documentation for contributors is in doc/modules/ROOT/pages/hacking_on_nrepl.adoc.

Two repository details are worth a mention. The project keeps an eastwood.clj configuration file at the root and a clj-kondo directory, and it carries a .cljfmt.edn, so the lint configuration is versioned rather than left to defaults. The second is the release rule, which the Makefile spells out: deployment is performed by CI when a git tag prefixed with v is created, local deployment is not permitted because it skips measures, and a release tag has to carry the documentation version or the release never appears in the site version menu, since the tag cannot be fixed afterwards.

## How nREPL differs from a REPL server you write yourself

The most useful comparison is not with another tool, it is with the alternative of not adopting nREPL at all.

Suppose you need to evaluate code in a remote Clojure process for your own editor plugin. You could write your own server: open a socket, define your own request and response shapes, and write the matching client. That gives you complete control and no external dependency, at the cost of a protocol that only your tools speak, no third party client support, and a security and session design you have to invent.

nREPL takes the opposite position. The protocol is specified independently of the implementation, a set of common operations is already agreed, and the client side already exists in CIDER, Calva, vim-fireplace and rebel-readline. The cost of the standard is that you inherit its operation set and its stability contract, and that your tool is constrained to what the specification describes, with a formal process for anything new.

The project itself points at two comparisons for people who want more detail. The documentation links a detailed comparison with other REPL servers, naming prepl as an example, and it directs readers to a history document for the relationship between nREPL and the contrib tools.nrepl project. Those pages are the authority on the specific differences. What the README establishes is the shape of the choice: nREPL occupies the position of a specified, stable, widely implemented protocol rather than a single implementation.

One caveat applies to the ecosystem argument. The middleware mechanism is where extensions live, and the Piggieback case shows the boundary: middleware is a separate artifact that has to be compatible with the server it extends, so the compatibility pledge of nREPL itself does not automatically extend to the middleware you add on top.

## EPL terms and a release cadence you can plan around

The licence is the Eclipse Public Licence, named in the licence section of the project with the file epl.html holding the text, and the copyright is held by Chas Emerick, Bozhidar Batsov and contributors. For tooling that talks to nREPL over a network, the EPL's file level copyleft shape is the part a distributor should look at, though whether it matters to you depends on what you distribute, and that question belongs with your own legal advice rather than with a review.

The release history shows a project that ships on a predictable rhythm with a deliberate compatibility stance. v1.6.0 came out on 2026-02-26, v1.7.0 on 2026-04-14 and v1.8.0 on 2026-10-02, so the minor version has moved three times in the past year. The repository is not archived, and the last push was on 2026-10-18, which is two days before the tagged 1.8.0 release window closed and indicates work continuing between releases rather than a project settling into maintenance mode.

The two commitments together are the reason this dependency is unusual. A project can be busy and still break its consumers, and a project can promise compatibility and never ship. nREPL is doing both, and the release tooling reflects it: tags are the only deployment path, they must match a version pattern, they must carry the documentation version so the release appears in the site version menu, and the build fails when the generated middleware documentation drifts from the committed copy.

The upgrade cost for a client tool is therefore low, but it is not zero. Since the minor version can add operations, and since the documentation distinguishes stable from experimental features, the practical step after upgrading is to re-read the operation list and check that nothing you depend on has moved category.

## Conclusion

nREPL suits anyone building or maintaining a Clojure IDE integration, since the protocol is specified, the middleware descriptors are documented, and the compatibility pledge means a client written against one version keeps working across releases. It does not suit a ClojureScript shop that wants first class support, because that arrives through the Piggieback middleware rather than from the reference implementation, and it does not suit a project that needs a REPL server for a language other than Clojure without willingness to implement the protocol. Before adopting it, read the middleware descriptor list in doc/modules/ROOT/pages/ops.adoc, check that the operations your client relies on are marked stable rather than experimental, and confirm the EPL terms in epl.html match how you intend to distribute the tooling.

## FAQ

### What is nREPL and who uses it?

nREPL is a Clojure network REPL that provides a REPL server and client plus common APIs for tools that need to evaluate Clojure code in remote environments. It powers development tools including CIDER, Calva, vim-fireplace and rebel-readline.

### Is the nREPL protocol stable and backwards compatible?

The project describes itself as extremely stable, says the protocol and API are battle tested, and pledges to evolve them only in backwards-compatible ways. The protocol is formally specified at spec.nrepl.org, and experimental features are marked explicitly in the documentation.

### Does nREPL support ClojureScript?

Partly. The reference implementation is Clojure-specific, and ClojureScript support is added through the Piggieback middleware. The project notes that in the future there may be implementations targeting ClojureScript directly.

### Can nREPL be used with languages other than Clojure?

Yes. The nREPL protocol is language-agnostic, and implementations of nREPL servers exist for several programming languages. The project also states that implementing new nREPL servers is pretty simple.

### What licence is nREPL released under?

The Eclipse Public Licence, with the text in the epl.html file in the repository and the copyright held by Chas Emerick, Bozhidar Batsov and contributors.

## Sources

- [Issues](https://github.com/nrepl/nrepl/issues)
- [nrepl/nrepl on GitHub](https://github.com/nrepl/nrepl)
- [Project website](https://nrepl.org)
- [README](https://github.com/nrepl/nrepl/blob/master/README.md)
- [Releases](https://github.com/nrepl/nrepl/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nrepl-nrepl