Clojure - deps.edn Reference
Table of Contents
Overview
The deps.edn file is a data file specifying all information needed to form a project classpath, including deps, paths, and external dependency repository information. The deps.edn file format is used by the tools.deps library and the Clojure CLI.
If you are building a tool that would like to leverage deps.edn, create well-known namespaced :aliases as a means to convey tool configuration, rather than adding new arbitrary tags elsewhere in the deps.edn data - these may not be preserved or conveyed during processing. Tools can access alias data via the basis at runtime, or programatically via tools.deps.
:paths
Paths specify the directories in the project that should be put on the project classpath, including both source and resources.
Paths are declared in a top level key :paths and are a collection of string paths or alias names. Alias names refer to a collection of paths defined in an alias (this can be done for reuse).
Paths should be subdirectories relative to the project root, such as "src" or "resources". Absolute paths are supported but should be used only in exceptional cases. Paths outside the project root will trigger a warning message - these are deprecated and may be removed in the future.
If used, alias names should refer to a path vector in the alias data:
{:paths [:clj-paths :resource-paths]
:aliases
{:clj-paths ["src/clj" "src/cljc"]
:resource-paths ["resources"]}}Paths are always included in the beginning of the classpath, in the order provided in the expanded :paths collection.
:deps
Dependencies are declared in deps.edn with a top level key :deps - a map from library to coordinate.
The library name is a qualified symbol. Unqualified symbols are treated as name/name but this usage is deprecated. Coordinates (and library names to some extent) are specific to the coordinate types below.
Dependencies are expanded from this top-level set of deps to include all transitive deps. Generally, the newest version is selected (barring other constraints - see the docs). Dependencies will be put on the classpath after any paths, sorted by a) depth from root and b) alphabetical sort of deps at a certain depth. This order should be stable.
Examples:
{:deps
{;; example maven dep
org.clojure/tools.reader {:mvn/version "1.1.1"}
;; example git dep
io.github.sally/awesome {:git/tag "v1.2.3" :git/sha "123abcd"}
;; example local dep
my.dev/project {:local/root "../project"}
;; example local jar
my.driver/jar {:local/root "../libs/driver.jar"}
}}Maven deps
The Maven procurer uses the qualifier mvn and is used to retrieve library artifacts from Maven repositories, the standard repository manager in the Java ecosystem. Libraries are downloaded as .jar files and stored in the Maven local repository cache (located in ~/.m2/repository by default or override with :mvn/local-repo). Other JVM-based tools may also use this cache.
Maven libraries are located in Maven repositories using "Maven coordinates", typically the groupId, artifactId, and version (sometimes also abbreivated as GAV). In deps.edn, the library name is parsed as groupId/artifactId and the version is taken from :mvn/version. Some Maven artifacts also have a "classifier", which is a variant of a particular artifact. In the Maven procurer, classifiers are included at the end of the lib name, separated by a $ in this format: groupId/artifactId$classifier.
Currently, only jar artifacts are supported. Support for other artifact types (particularly Bill of Materials poms) may be added in the future.
Note that Maven <repositories> declared in dependencies or transitive dependencies are ignored. All repositories needed by the full set of dependencies must be declared in the project deps.edn using :mvn-repos.
Git deps
The git procurer supports direct use of source-based libs hosted in Git repositories. Git libs are downloaded by default to the ~/.gitlibs directory. The working tree is checked out and cached for each sha included as a dependency.
To specify a git lib as a dependency, two pieces of information must be known - the Git repo url and a specific sha. Using movable references like branch names is not supported.
Git coordinates have the following attributes:
-
:git/url- optional, Git url (may be inferred from lib name, see below) -
:git/sha- required, either a full 40-char sha or a sha prefix can be provided in combination with a tag (:shais also accepted for backwards compatibility) -
:git/tag- optional, git tag name (may be used only in combination with a:git/sha,:tagaccepted for backwards compatibility)
The git url must either be provided or inferred from the lib name. If provided, the :git/url takes precedence. Lib to url convention is as follows:
| Lib format | Inferred :git/url |
|---|---|
io.github.ORG/PROJECT |
|
com.github.ORG/PROJECT |
|
io.gitlab.ORG/PROJECT |
|
com.gitlab.ORG/PROJECT |
|
io.bitbucket.ORG/PROJECT |
|
org.bitbucket.ORG/PROJECT |
|
io.beanstalkapp.ORG/PROJECT |
|
com.beanstalkapp.ORG/PROJECT |
|
ht.sr.ORG/PROJECT |
|
org.codeberg.ORG/PROJECT |
|
page.codeberg.ORG/PROJECT |
|
This is an example deps.edn including two valid git deps, the first with inferred git url, git tag, and sha prefix, and the second with explicit git url and full sha:
{:deps
{;; implied git url, tag + sha prefix
io.github.clojure/tools.deps.graph {:git/tag "v1.1.68" :git/sha "6971bb4"}
;; explicit git url, full sha
org.clojure/tools.build {:git/url "https://github.com/clojure/tools.build.git"
:git/sha "ba1a2bf421838802e7bdefc541b41f57582e53b6"}}}:git/tag
:git/tag is an optional coord key that indicates the semantics of the sha by specifying the tag. If the :git/tag is provided, the :git/sha can be a short sha instead of a full 40-character sha.
:git/sha
:git/sha is a required coord key. If the :git/tag is provided it can be the prefix sha (they must unpeel to the same commit), otherwise it should be a full 40-char sha.
When selecting a version from between sha A and sha B where B has A as an ancestor, then B will be preferred (the "most descendant" one). If A and B do not have an ancestor/descendant relationship (commits in parallel branches for example), this is an error and classpath construction will fail.
Local deps
Local deps refer to either a directory or a jar file on disk. The :local/root attribute is required and may be either absolute or relative.
:local/root
For a local project directory, the :local/root should be a directory path, either absolute or relative to the location of the project directory.
For a jar file, the :local/root should be either absolute or relative path to a jar file. If the jar includes a pom.xml file, it will be used to find transitive deps
:exclusions
The :exclusions attribute takes a vector of lib symbols to exclude as transitive deps from this dependency. This attribute can be used on any dependency.
:deps/root
The :deps/root attribute indicates a relative directory path within a file-based dep to search for the manifest file. It is commonly used with monorepo style projects to specify a dep root in a directory below the repo root.
:deps/manifest
When a git or local project is included, the project type is auto-detected based on manifest files deps.edn and pom.xml. If both exist, deps.edn is preferred.
The :deps/manifest attribute specifies the project manifest type and overrides auto detection, useful values are :deps, :pom. (Other values are :mvn, and :jar but these don’t need to be specified.)
:aliases
Aliases give a name to a data structure that can be used either by the Clojure CLI itself or other consumers of deps.edn. They are defined in the :aliases section of the config file.
:extra-deps is the most common modification - it allows you to add extra dependencies to the base dependency set. The value is a map of library to coordinate:
{:extra-deps {criterium/criterium {:mvn/version "0.4.4"}}}:override-deps
:override-deps overrides the coordinate version chosen by the version resolution to force a particular version instead. The value is a map of library to coordinate:
{:override-deps {org.clojure/clojure {:mvn/version "1.9.0"}}}:default-deps
:default-deps provides a set of default coordinate versions to use if no coordinate is specified. The default deps can be used across a set of shared projects to act as a dependency management system:
{:default-deps {org.clojure/core.cache {:mvn/version "0.6.4"}}}:deps / :replace-deps
:deps and :replace-deps are synonyms and define a deps map that REPLACES the project :deps. The value is a map of lib to coordinate.
:extra-paths is used to include source paths in addition to your standard source paths, for example to include directories of test source:
{:extra-paths ["test" "resources"]}Note that external paths should be at or under the root directory of the project (location of the deps.edn file).
:paths / :replace-paths
:paths and :replace-paths are synonyms and define a collection of string paths to REPLACE the project :paths.
:classpath-overrides
:classpath-overrides specifies a location to pull a dependency that overrides the path found during dependency resolution, for example to replace a dependency with a local debug version. Many of these use cases are ones where you would be tempted to prepend the classpath to "override" something else:
{:classpath-overrides
{org.clojure/clojure "/my/clojure/target"}}:ns-default
The :ns-default attribute is a namespace symbol that will be used as the default namespace for attributes that provide an unqualified symbol, most importantly :exec-fn.
:ns-aliases
The :ns-aliases attribute is a map of alias symbol to namespace symbol that will be used to resolve qualified symbols, most importantly :exec-fn.
:exec-fn
The :exec-fn symbol defines the default function to be invoked when using -X function execution in the Clojure CLI:
;; deps.edn
{:aliases
{:my-fn
{:exec-fn my.qualified/fn
:exec-args {:my {:data 123}
:config 456}}}}The :exec-fn symbol is resolved with the following rules:
-
If function is unqualified, use the namespace in the
:ns-defaultkey in the arg map (if none, this is an error) -
If function is qualified, and the qualifier is an alias in the arg map under
:ns-aliases, use that namespace -
Else use the fully qualified function symbol
:exec-args
The :exec-args map specifies key-value pairs that are provided when executing an :exec-fn function with -X or -T in the Clojure CLI. These kv pairs are effectively provided first, so can be overridden by subsequent kv pairs on the command line.
:jvm-opts
The :jvm-opts are a collection of string JVM options to be provided when executing the Clojure CLI with -M, -X, -T, or a repl.
:main-opts
The :main-opts are a collection of string options provided to a program started with -M on the Clojure CLI. If multiple aliases are merged that provide main args, only the args from the last one are used (they do not accumulate or combine). Additional main opts may be provided on the command line after -M.
Procurer config
Maven
The Maven procurer uses the Maven resolver and Maven repository system to download artifacts. This is described further in the Maven deps section. Some options can be configured in the deps.edn.
:mvn/local-repo
By default, Maven uses the ~/.m2/repository directory as a local cache of downloaded poms and jars. The :mvn/local-repo is a string path to an alternate directory to use as the local Maven cache.
:mvn/repos
The Maven procurer always uses two built-in repositories that are always checked first in this order:
{"central" {:url "https://repo1.maven.org/maven2/"}
"clojars" {:url "https://repo.clojars.org/"}}You can supply additional repositories in the :mvn/repos key as a map of repository name to a map of additional repository attributes described below. Repository names are arbitrary. The :url attribute is required, all others are optional. Repositories declared in dependency poms or deps.edn are not used - all necessary repositories must be defined in the top deps.edn file being used.
:url
The :url is a string url to the repository root.
http:// urls are not supported by default, but see clojure_cli for information on the CLOJURE_CLI_ALLOW_HTTP_REPO if you need this.
:releases and :snapshots
The :releases attribute is optional, but can be used to override the default repository configuration for release (non-snapshot artifacts):
{:mvn/repos
{"my-releases" {:url "https://example.com/releases"
:snapshots {:enabled false}
:releases {:enabled true
:update :daily
:checksum :fail}}}}The :snapshots attribute is the same as the :releases attribute, but applies repository policy for snapshot artifacts.
Repository attributes:
-
:enabledis a boolean, default=true. Sometimes this is used to target a repository only for releases or snapshots. -
:updateis a flag for how often to check the repo for updates, valid values are:daily(default),:always,:never, or an interval in minutes (integer). -
:checksumis a flag for checksum validation, one of:warn(default),:fail,:ignore.
Clojure CLI tools loaded from Github or a local dir can provide default tool configuration in their deps.edn using the :tools/usage key. All users of the tool will get this configuration as part of their tool installation.
Prep lib
:deps/prep-lib
Source libs with Clojure source can immediately be added to the classpath of a project using it. However, some source libs require some preparation before they can be added, for example due to needing Java compilation, or copying / replacing resource files, etc. The Clojure CLI will now detect projects that need preparation and prevent the program from being run from source unless the prep step has been completed.
If your library needs preparation, add the :deps/prep-lib key to your deps.edn:
{:paths ["src" "target/classes"]
:deps/prep-lib
{:ensure "target/classes"
:alias :build
:fn compile-java}}Runtime basis
The runtime basis is a representation of the dependency environment when the Clojure runtime starts. It includes information about the dependencies, classpath, and how the basis was created.
The runtime basis can be accessed from within Clojure, using the clojure.java.basis API. It includes access to both the initial basis and the current basis, which may be modified by the add-libs and related functions.
Index of runtime basis attributes
{;; The basis is a superset of the merged deps.edn
;; so may contain all of those attributes plus these:
;; Project paths
:basis-config {:dir "project/dir"
:root :standard|path|map
:user :standard|path|map
:project :standard|path|map
:extra path|map
:aliases [:alias1 ...]
:args {arg val}}
:argmap {arg val}
:libs {lib coord}
:classpath {classpath-path classpath-info}
:classpath-roots [classpath-path ...]}
:basis-config
The :basis-config attribute contains the parameters used when the basis was created and should be sufficient to recreate the basis later. That property is in particular used by sync-deps.
The :basis-config may have the following attributes:
-
:dir- absolute or relative path to the project directory (containing project deps.edn), defaults to current directory -
:root- root deps.edn source, one of:standard(read from classpath), a path, or a literal map -
:user- user deps.edn source, one of:standard(read from user config dir), a path, or a literal map -
:project- project deps.edn source, one of:standard(read from:dir), a path, or a literal map -
:extra- extra deps.edn source, either a path or a literal map -
:aliases- a vector of supplied alias keywords providing argmap keys -
:args- a map of extra argmap args, applied after alias argmaps are merged
:argmap
The basis :argmap contains the merged argmap that was used when resolving dependencies and computing the classpath. The argmaps can be supplied either indirectly by the :aliases or directly via the :args key when creating the basis.
:libs
The basis :libs key is a map of every dependency, both direct and transitive, included in the basis classpath. The :libs value is a map from lib name (qualified symbol) to lib coordinate with some additional keys. While most of the keys are non-normative, one important added key is the :paths vector of file paths to add to the classpath for this lib.