Working with Deps

Deps is a simple tool for managing dependencies in Clojure projects. It's designed by the Clojure core team to facilitate two main things - managing dependencies and creating a classpath. It deliberately takes a different approach to Leiningen which is a batteries-included do-everything tool, but Deps has seen a lot of uptake because for the projects it works for it works very well, and it's considerably simpler than Leiningen and other alternatives. Let's see how to use Deps with Cursive.

Configuring Deps

Deps does require us to set a few things up before we get started. Deps is integrated with the relatively new Clojure command line tooling, but at the time of writing the command line tools are still not available on Windows. So the install instructions will depend on your OS. You can also perform this configuration when creating or importing your first Deps project, as shown below.

macOS and Linux

Install the command line tools according to the instructions. Then, go to Settings→Build, Execution, Deployment→Build Tools→Clojure Deps in the tree on the left.

In this panel, select "Use CLI tools", and enter the path to the clojure command if required. Cursive will try to find it in various standard locations, but if your package manager installs it in a non-standard location enter the path here. When the path is correct, Cursive should display the CLI version and config dir location as shown here. If that's showing, then you should be good to go!


If you're running Windows, then select the "Use tools.deps directly" option. This means that Cursive will download tools.deps.alpha and use it as a library rather than calling out to the command line. Press Refresh, and Cursive will download the list of available versions - generally the most recent is the one you want. Once you have the version you want selected in the dropdown, press Download and Cursive will download that version to use.

If you're in an environment where you don't have outbound access to the internet and you're using an internal Maven repo to fetch your deps, you can use the "Use private repo" option and specify the ID and the URL of your internal repo. Cursive will also respect the IntelliJ HTTP proxy configuration when fetching Deps.

Finally, there's one limitation of this approach. Currently the system deps.edn file is bundled with the command line tools, so this option will cause a version of that file bundled with Cursive to be used. You can also specify the path to the user deps.edn file you'd like Cursive to use, this can be useful when sharing config with WSL.

Create a new project with Deps

To create a new project in IntelliJ, if you're at the welcome screen, click the "Create New Project" link, or if you already have a project open in IntelliJ you can use File→New→Project.... In the following dialog, choose "Clojure" from the list of project types on the left-hand side. You'll then have a list of Clojure project types to choose from on the right. Here you can choose "Deps".

On the next screen, choose whether to use auto-import or not. This means that your project will be automatically refreshed after you modify the deps.edn file, and is generally a good idea.

On the next screen, give your project a name and decide where to put it:

Then, when you click "Finish" you'll have a new project to work with!

Import an existing Deps project

If you already have an existing project you'd like to start with, let's see how to do that. From the welcome screen, click the "Import Project" link, or if you already have a project open in IntelliJ you can use File→New→Project from Existing Sources.... Here, you can select either the deps.edn file or the directory containing it.

If required, select "Import project from external model" and select Deps.

In the next panel, the root directory of your project will be filled in for you. You can also choose to use auto-import (which means that your project will be automatically refreshed after you modify the deps.edn file) and to automatically create content roots (i.e. src and test directories) if they don't exist.

You can expand out the Global Clojure Deps settings section to configure Deps in a similar manner to the preferences pane earlier.

Finally, press 'Finish' to actually import the project.

Your project will then be opened and is ready to use.

Quick project import

For simple projects you don't need to explicitly import them. Just use File→Open..., select either the deps.edn file or the containing directory, and your project will be automatically imported.

Working with aliases

Often Deps projects will use aliases for different situations. Since aliases will often add source roots and dependencies that you'll need when working with your source code, you can let Cursive know which ones it should use when synchronising your project.

To do that, open the Deps toolwindow, then expand out the Aliases tree. Select the aliases you'd like to use when synchronising, then refresh your project using the icon.

Viewing your project dependencies

One thing that is very useful when working with Deps is being able to see a tree of the dependencies of your project. On the command line you would use clojure -Stree to show this, but Cursive will show you this within the IDE too, also in the Deps toolwindow. The dependencies are nested in a tree structure so you can see how each dependency was pulled into your project:

Refreshing Deps dependencies

When you have updated your deps.edn file, you can press the icon to re-read the project file and refresh the project dependencies. This will be performed automatically after a short delay if you selected the auto-import option when setting up your project.

Working with multi-module projects

If you have a more complex project with multiple modules, Cursive will generally detect it automatically and set everything up. However because of a limitation of the IntelliJ framework which the Cursive Deps support uses, only one project at a time can be imported. This can be problematic because often the root directory of your main project isn't exactly where that one project is located. Here's how to work around this:

We'll start by creating an empty project. If you're at the welcome screen, click the "Create New Project" link, or if you already have a project open in IntelliJ you can use File→New→Project.... In the following dialog, choose "Empty Project" from the list of project types on the left-hand side.

In the next pane, give your project a name and enter the location of the root of your main project:

When you click Finish, a new empty project will be set up and the Project Structure view will be opened so you can add some modules to it. Select Modules in the list on the left hand side, then click the icon to import a module to the project:

As before, we can adjust some settings of the new module, then press OK.

As you can see here, Cursive has actually imported various modules, not just one. This is because it transitively follows the local dependencies between projects (using :local/root in the deps.edn files) and imports all those too. You can either continue to import more modules if required, or just press OK if you're done.

And your new project is now set up and ready to use. You can then add new modules to the project using either the button in the Deps tool window, or using the context menu in the project tool window. You can remove Deps modules from the project and optionally remove the corresponding IntelliJ module using the in the Deps tool window.

Working with Leiningen Other Project Types