Like Emacs itself, almost every part of CIDER is configurable. The CIDER developers have tried to implement some reasonable defaults that should work for a large portion of the Clojure community, but we know that there is nothing approaching a "one size fits all" development environment and we’ve tried to create points of customization that can account for many different peoples' preferences. In this way, you should be able to make CIDER as comfortable as possible for you.
This section doesn’t describe every possible customization that CIDER offers, but here are some of the most popular.
|You can see every single customizable configuration option with the command M-x customize-group RET cider.
By default, CIDER enables
cider-mode in all
after it establishes the first CIDER connection. It will also add a
clojure-mode hook to enable
cider-mode on newly-created
buffers. You can override this behavior, however:
(setq cider-auto-mode nil)
enrich-classpath is a program/plugin/wrapper that allows CIDER to access to the sources and javadocs of a given project’s Java files: your own files, those from your dependencies, and those from the JDK.
With that, CIDER can show better completions, navigation, documentation, and stacktrace integration.
For Lein users, it has the additional benefit of running a single JVM, instead of the two JVMs that Lein programs typically involve.
enrich-classpath is still in beta and defaults to being disabled.
You can enable it by setting the
cider-enrich-classpath defcustom to
With it enabled,
cider-jack-in will activate enrich-classpath, given the following conditions:
You are on macOS/Linux
You are launching a vanilla JVM repl (and not a cljs repl, or a clj+cljs repl)
You are using
cider-connect, please follow enrich-classpath’s own instructions.
…these conditions will be progressively relaxed.
It’s worth noting that
cider-jack-in will fall back to the original command if enrich-classpath failed, for whatever reason.
|The default here was changed in CIDER 1.0.
By default, CIDER won’t prompt you for a symbol when it executes
interactive commands that require a symbol (e.g.
commands operate on the symbol at point and prompt you to provide
a symbol if they can’t obtain one automatically.
If you set
t, this behavior will be inverted and
CIDER will always prompt you to confirm the symbol on which a command
will operate. This behavior is useful, as it allows you to edit the
inferred symbol, before some operation is carried out with it (and you get to
see what was inferred by
(setq cider-prompt-for-symbol t)
Many interactive commands that operate on the symbol at point,
accept a prefix argument that flips the behavior configured via
cider-prompt-for-symbol for the current command invocation.
By default M-. and other commands that jump to a definition have the following behavior:
If the definition buffer is visible simply switch to it.
Otherwise, use the current window to show the definition.
Other behavior is possible, and is controlled with
cider-jump-to-pop-to-buffer-actions; the value of this is passed as the
action argument to
The default value is
Some people might prefer to always display the definition in the current window. Here’s how you can achieve this:
|Keep in mind this might cause problems with some special buffers (e.g. test report buffers), as when you try to navigate to a definition this will clobber the special buffer.
For other possibilities, see the documentation for
You jump to
core.clj is not being displayed in another
window in the current frame.
With both the default behavior and the alternative behavior defined above, the
map will be shown in the current window.
You jump to
core.clj is being displayed in another window
in the current frame.
With the default behavior, the definition of
map will be shown in the current
window; you will now have two windows showing
core.clj, and the existing
core.clj window will be unchanged.
With the alternative behavior defined above, the definition of
map will be
shown in the existing
core.clj window; all windows will show the same buffer as
before the jump, and the current window will now be the one showing
Out-of-the box, CIDER uses the standard
completing-read Emacs mechanism. While
it’s not fancy it certainly gets the job done (just press TAB). There
are, however, ways to improve upon the standard completion if you wish to.
icomplete is bundled with Emacs and enhances the default minibuffer completion:
You can learn more about
If you’re fine with installing a third-party package for enhanced minibuffer completion you can’t go wrong with the modern and versatile ivy.
By default CIDER will display an inspirational message when a new connection is
established. This behavior is configurable via
;; make the message more educational
(setq cider-connection-message-fn #'cider-random-tip)
;; disable this extra message altogether
(setq cider-connection-message-fn nil)
The default message are stored in the variable
you can tweak easily yourselves:
(add-to-list 'cider-words-of-inspiration "Moar inspiration!")
Of course, it goes without saying that you can do the same with
|This is probably one of the most important CIDER features. Disable those amazing messages at your own risk!
If you want to see all communications between CIDER and the nREPL server:
(setq nrepl-log-messages t)
CIDER will then create buffers named
*nrepl-messages conn-name* for
The communication log is tremendously valuable for debugging CIDER-to-nREPL problems and we recommend you enable it when you are facing such issues.
If you’re finding that
buffers are cluttering up your development environment, you can
suppress them from appearing in some buffer switching commands like
(setq nrepl-hide-special-buffers t)
If you need to make the hidden buffers appear When using
switch-to-buffer, type SPC after issuing the command. The
hidden buffers will always be visible in
list-buffers (C-x C-b).
To prefer local resources to remote resources (tramp) when both are available:
(setq cider-prefer-local-resources t)
If you are running Clojure within a Docker image, or doing something similar (i.e. you’re
cider-connect`ing to a process,
and there’s a directory mapping for your source paths), you typically need to set `cider-path-translations
for jump-to-definition to properly work. For instance, suppose your app is
running in a docker container with your source directories mounted there as volumes. The
navigation paths you’d get from nREPL will be relative to the source in the
docker container rather than the correct path on your host machine. You can add
translation mappings easily by setting the following (typically in
(cider-path-translations . (("/root/.m2" . "/Users/foo/.m2")
("/src/" . "/Users/foo/projects")))))
Each entry will be interpreted as a directory entry so trailing slash
is optional. Navigation to definition will attempt to translate these locations, and
if they exist, navigate there rather than report that the file does not
exist. In the example above, the
.m2 directory is mounted at
and the source at
/src. These translations would map these locations
back to the user’s computer so that navigation to definition would work.
eval pseudo-variable you can make the translation dynamic, enabling
the possibility of sharing the
.dir-locals.el across a team of developers with
((nil . ((eval . (customize-set-variable 'cider-path-translations
(cons "/src" (clojure-project-dir))
(cons "/root/.m2" (concat (getenv "HOME") "/.m2"))))))))
In this example, the path
/src will be translated to the correct path of your
Clojure project on the host machine. And
/root/.m2 to the host’s
You need to run
lein deps (or
clojure -P, etc) in the host machine in order for
navigation to fully work, at least once, and then, preferably, every time your Maven dependencies change.
This allows the
.m2 part of
cider-path-translations to be actually useful.
If you can’t or won’t do that, you can use TRAMP capabilities (which CIDER supports) instead of
cider-path-translations. For that, you’d typically need to set up a SSH daemon
within your Docker image.
You can hide all nREPL middleware details from
commands by customizing the variable
cider-filter-regexps. The value of this
variable should be a list of regexps matching the pattern of namespaces you want
to filter out.
Its default value is
'("^cider.nrepl" "^refactor-nrepl" "^nrepl"),
the most commonly used middleware collections/packages.
An important thing to note is that this list of regexps is passed on to the middleware
without any pre-processing. So, the regexps have to be in Clojure format (with twice the number of backslashes)
and not Emacs Lisp. For example, to achieve the above effect, you could also set
cider-filter-regexps, you could use the Emacs customize UI,
An alternative is to set the variable along with the other CIDER configuration.
(setq cider-filter-regexps '(".*nrepl"))
By default contents of CIDER’s special buffers such as
*cider-doc* are line truncated. You can set
nil to make those buffers use word
wrapping instead of line truncating.
(setq cider-special-mode-truncate-lines nil)
This variable should be set before loading CIDER (which means before
require-ing it or autoloading it).
CIDER provides the hooks
that get triggered when an nREPL connection is established or closed respectively.
Here’s how CIDER uses the first hook internally to display its famous inspirational messages on connect:
(defun cider--maybe-inspire-on-connect ()
"Display an inspiration connection message."
(message "Connected! %s" (funcall cider-connection-message-fn))))
(add-hook 'cider-connected-hook #'cider--maybe-inspire-on-connect)
There are also lower-level
nrepl-disconnected-hook that CIDER uses internally. Most of the time end-users would be better off using
the CIDER-level hooks instead.