Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 36 ยท Getting Started

Installing Clojure and Using the REPL

Install the Clojure CLI, start a REPL, evaluate forms interactively, and learn about deps.edn, Leiningen, Babashka and editor setups such as Calva, CIDER and Cursive.

To write Clojure you need two things: a Java runtime and the Clojure tooling. The tooling gives you a command that starts a REPL (Read-Eval-Print Loop), which is where most Clojure development happens. In this lesson you will install Clojure, start a REPL, and learn the tools you will meet in real projects.

The commands below run in your own terminal. The site cannot run Clojure, so everything here is read-only except the small JavaScript model of a REPL near the end.

What you need

Clojure itself is a library (a .jar file), so it needs a Java runtime. Install a recent JDK first (version 21 or newer is a good choice; any supported long-term-support release works). Check it from a terminal:

Terminal
java -version

If this prints a version number you are ready. Otherwise install a JDK from your operating system's package manager or from a vendor such as Eclipse Temurin.

Installing the Clojure CLI

The Clojure CLI (commands clojure and clj) is the official tool. It downloads libraries, builds a classpath and starts programs or REPLs.

  • macOS (Homebrew): brew install clojure/tools/clojure
  • Linux: use the official install script from clojure.org, or your distribution's package.
  • Windows: use the community-supported installer such as scoop, or the Windows PowerShell module ClojureTools from clojure.org. WSL (Windows Subsystem for Linux) also works well.

Check that it works:

Terminal
clj --version

clj is the same as clojure but wraps it in rlwrap when available, giving you arrow-key history in the REPL. If you are on Windows without rlwrap, use clojure.

Starting a REPL

Run clj with no arguments. You get a prompt, which waits for a form (a piece of Clojure code):

CLOJURE
user=> (+ 1 2 3)
6
user=> (str "Hello, " "REPL")
"Hello, REPL"
user=> (inc 41)
42

user=> means you are in a namespace called user. Each line goes through four steps: the reader turns text into data, the evaluator runs it, the result is printed, and the loop starts again. Press Ctrl+D to exit.

Two special names remember recent results: *1 is the last value, *2 the one before. If something throws an exception, *e holds it, and (pst) prints a short stack trace.

The REPL loop

Read Text becomes data.
Eval Data is run as code.
Print The result is shown.
Loop Ready for the next form.

You keep the same running program the whole time.

1 / 2

Documentation from the REPL

The REPL can tell you about any function. Load the helpers first and use them:

CLOJURE
(require '[clojure.repl :refer [doc source apropos dir]])

(doc map)         ; prints the docstring and signatures
(source filter)   ; prints the source of a function
(apropos "split") ; every name containing "split"
(dir clojure.string) ; all public names in a namespace

Inside clj these helpers are already referred in the user namespace, so (doc map) works straight away. Using doc constantly is one of the fastest ways to learn the standard library.

Projects and deps.edn

Real programs live in files. With the Clojure CLI, a project has a file named deps.edn at its root. It lists dependencies and where your source code lives:

CLOJURE
{:paths ["src"]
 :deps  {org.clojure/clojure {:mvn/version "1.12.0"}
         metosin/malli       {:mvn/version "0.16.4"}}
 :aliases
 {:test {:extra-paths ["test"]}}}

The file is itself Clojure data: a map with keyword keys. :paths says where source files are, :deps names libraries and versions (the library name looks like group/artifact), and :aliases define optional variations such as test settings. The version numbers above are examples; look up current versions when you start a project.

Run a function from the command line with -M (main) or -X (exec a function with arguments):

Terminal
clojure -M -m my.app.core          # runs -main in namespace my.app.core
clojure -X my.app.core/run :port 8080

Other tools you will meet

  • Leiningen (lein): the older and still very common build tool, configured with project.clj. Many tutorials and existing projects use it. lein repl starts a REPL, lein run runs the project and lein uberjar builds a standalone jar.
  • Babashka (bb): a fast-starting Clojure interpreter for scripts. It starts in milliseconds, so it is perfect for command-line tasks. It supports most of the core language.
  • ClojureScript (shadow-cljs): compiles the language to JavaScript for browser and Node.js programs.

All of them speak the same language; the differences are in how projects are built and run.

Editor-connected REPLs

Typing into a terminal REPL works, but the real workflow is to connect your editor to a running REPL and evaluate code right from the file you are editing:

  • Calva (VS Code): the most beginner-friendly option. It can start a REPL for you ("Jack-in") and has structural editing.
  • CIDER (Emacs) and Cursive (IntelliJ IDEA): popular among full-time Clojure developers.
  • Conjure (Neovim) and Vim-fireplace for Vim users.

They connect through nREPL, a network protocol: a REPL server runs in your program, and the editor sends forms to it. Two habits worth learning on day one are evaluating the form under the cursor and evaluating the whole file. Because the program keeps running, you rarely restart it.

Structural editing

Clojure code is made of balanced brackets, so editors help you edit whole forms instead of single characters. The two operations to learn first are slurp (pull the next form into the current list) and barf (push the last form out). With them, you almost never fix unbalanced parentheses by hand. Turn on "auto-balance" or paredit-style editing in your editor and let it handle brackets.

A REPL model in the browser

To get a feel for the loop, here is a JavaScript stand-in for a REPL. It keeps a "session" and stores recent results in last, similar to *1. It is not Clojure; it only models the interactive style of work.

JS Stand-in: a tiny REPL session

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The important point is that the session state stays alive between forms. In Clojure you can also define functions in the REPL (def, defn) and call them again later, changing their definitions without restarting.

JS Stand-in: redefining a function in a live session

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does REPL stand for?

    The REPL reads a form, evaluates it, prints the result and loops.
  2. 2. Which file lists dependencies for a Clojure CLI project?

    deps.edn is used by the Clojure CLI; project.clj belongs to Leiningen.
  3. 3. What does (doc map) do in the REPL?

    doc prints the docstring and argument lists for a var.
  4. 4. Why do editors connect to the REPL through nREPL?

    nREPL is a network protocol that lets editors evaluate forms in the running process.

Summary

  • Install a JDK, then the Clojure CLI; clj starts a REPL.
  • The REPL reads, evaluates, prints and loops; doc, source, apropos and dir teach you the library.
  • deps.edn describes a CLI project; Leiningen (project.clj) is the older alternative; Babashka is for fast scripts.
  • Editors such as Calva, CIDER and Cursive connect to a running program via nREPL.

Next: Clojure Syntax and Evaluation