Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…
Cannot retrieve contributors at this time
101 lines (75 sloc) 3.99 KB

Leiningen Plugins

Leiningen tasks are simply functions named $TASK in a leiningen.$TASK namespace. So writing a Leiningen plugin is pretty straightforward; as long as it's available on the classpath, Leiningen will be able to use it.

To use a plugin, add it to your project.clj :dev-dependencies and run "lein deps". Then you'll be able to invoke the tasks it provides with "lein $TASK". If you want plugins to be available for all the projects you use, you can place their jars in ~/.lein/plugins.

Writing a Plugin

Start by generating a new project with "lein new myplugin", and add a leiningen.myplugin namespace with a myplugin function.

Some tasks may only be run in the context of a project. For tasks like this, name the first argument project. Leiningen will inspect the argument list and pass in the current project if needed. The project is a map which is based on the project.clj file, but it also has :name, :group, :version, and :root keys added in. If you want it to take parameters from the command-line invocation, you can make the function take more arguments.

Tasks without a project argument will be able to be run from anywhere.

Note that Leiningen is an implied dependency of all plugins; you don't need to explicitly list it in the project.clj file.

The docstring from the plugin's namespace will be displayed by the "lein help" task. The function's arglists will also be shown, so pick argument names that are clear and descriptive.

If your task returns an integer, it will be used as the exit code for the process.

You can set up aliases for your task by conjing a pair of strings with alias->task-name mappings on to the leiningen.core/aliases atom:

(swap! leiningen.core/aliases conj ["-v" "version"])


If your plugins need to do a fair amount of filesystem-y things, you may want to take a look at using Ant tasks to do them since the JDK lacks a lot of simple functionality of this kind. Using the Ant API directly is a pain, but it can be eased to a degree using Lancet. Lancet is the Clojure adapter for Ant that is developed as the sample project in the Programming Clojure book.

You can look over the Ant API documentation's listing of tasks to find an appropriate task. See the deps task for an example of how to call a task from Clojure.


You can modify the behaviour of built-in tasks to a degree using hooks. Hook functionality is provided by the Robert Hooke library. This is an implied dependency; as long as Leiningen 1.2 or higher is used it will be available.

Inspired by clojure.test's fixtures functionality, hooks are functions which wrap tasks and may alter their behaviour by using binding, altering the return value, only running the function conditionally, etc. The add-hook function takes a var of the task it's meant to apply to and a function to perform the wrapping:

(use 'robert.hooke)

(defn skip-integration-hook [task & args]
  (binding [clojure.test/test-var (test-var-skip :integration)]
    (apply task args)))

(add-hook #'leiningen.test/test skip-integration-hook)

Hooks compose, so be aware that your hook may be running inside another hook. To take advantage of your hooks functionality, projects must set the :hooks key in project.clj to a seq of namespaces to load that call add-hook. Note that in Leiningen 1.2, hooks get loaded and used without being specified in project.clj; this is a bug. In 1.3 and on they are opt-in only.

See the documentation for Hooke for more details.

Have Fun

Please add your plugins to the list on the wiki.

Hopefully the plugin mechanism is simple and flexible enough to let you bend Leiningen to your will.

Jump to Line
Something went wrong with that request. Please try again.