Managing dependencies

Dependency syntax

Dependencies are declared in Scala CLI according to the following format:

groupID:artifactID:revision

This is similar to how you declare dependencies in SBT with the % character. For example:

org.scala-lang.modules:scala-parallel-collections_2.13:1.0.4

You can also skip explicitly stating the Scala version in the artifact name by repeating the : character after the groupID (similarly to how you can do the same with %% in SBT). This is just a shortcut, Scala CLI will still add the Scala version for you when fetching the dependency. Also, this only applies to Scala dependencies.

org.scala-lang.modules::scala-parallel-collections:1.0.4

Java and other non-scala dependencies follow the same syntax (without the :: for implicit Scala version, of course). For example:

org.postgresql:postgresql:42.2.8

Repositories

Sometimes dependencies are published into non-standard repositories, like nightly builds published to Sonatype Snapshots. Scala CLI can use additional maven and ivy repositories with the repository directive or --repository command line options:

//> using repository sonatype:snapshots

or

scala-cli --repository "https://maven-central.storage-download.googleapis.com/maven2"

Both directive and command line option accept predefined repository definitions (see below) or a URL of the root of Maven repository.

Repositories can also be resolved from the COURSIER_REPOSITORIES environment variable, but this is not recommended (more in Coursier documentation).

Predefined repositories

predefined repository	kind	description
central	Maven (root)	Used by default, default repository for most Scala libraries
sonatype:snapshots	Maven (root)	Repositories where most Scala libraries publish its snapshots / nightly builds. Used when X.nightly is used as Scala version e.g. 3.1.nightly.
sonatype-s01:snapshots	Maven (root)	This repository is similar to the sonatype:snapshots repository but is dedicated for accounts that were created after February 2021 and which publish snapshots of their libraries.
snapshots	Maven (root) and Maven S01 (root)	An alias for sonatype:snapshots and sonatype-s01:snapshots.
ivy2local	Ivy	Local ivy repository, used to publish things locally (e.g. by publishLocal). Localized in <ivy-home>/local, usually <user-home>/.ivy/local.
m2Local	Maven	Local maven repository, localized in <user-home>/.m2/repository
jitpack	Maven	jitpack supports github repo as dependency. Syntax is using repository "jitpack"

Scala CLI delegates parsing of predefined repositories to Coursier and full details can be obtained from Coursier source code (here and here)

Excluding Transitive Dependencies

To exclude a transitive dependency from a Scala CLI project use the exclude parameter:

• exclude=org%%name - for Scala modules
• exclude=org%name - for Java modules

It requires passing the organization and module name of the dependency to be excluded. For example, let's say you have the following Scala code:

//> using dep com.lihaoyi::pprint:0.8.1
object Main extends App {
  println("Hello")
}

If you want to compile it with the pprint library but exclude its sourcecode dependency, you can use the exclude parameter as follows:

//> using dep "com.lihaoyi::pprint:0.8.1,exclude=com.lihaoyi%%sourcecode"
object Main extends App {
  println("Hello")
}

To exclude Scala modules, you can also use a single % but with the full name of the module name, like this:

//> using dep "com.lihaoyi::pprint:0.8.1,exclude=com.lihaoyi%sourcecode_3"
object Main extends App {
  println("Hello")
}

Dependency classifiers

To specify a classifier of a dependency in a Scala CLI project, use the classifier parameter:

• classifier={classifier_name}

If you want to use the pytorch dependency with the classifier linux-x86_64, use the classifier parameter as follows:

//> using dep "org.bytedeco:pytorch:1.12.1-1.5.8,classifier=linux-x86_64"
object Main extends App {
  println("Hello")
}

caution

When using the classifier, exclude or others parameters, it is necessary to wrap the value of dependency within double quotes ". If this is omitted, Scala CLI treats these parameters as dependencies, resulting in a dependency parsing error.

Test dependencies

It is possible to declare dependencies limited to the test scope with the using test.dep directive.

//> using test.dep org.scalameta::munit::0.7.29

More details can be found in the using directives guide.

Specifying dependencies from the command line

You can add dependencies on the command line, with the --dependency option:

println("Hello")

scala-cli compile Sample.sc \
  --dependency org.scala-lang.modules::scala-parallel-collections:1.0.4

You can also add a URL fallback for a JAR dependency, if it can't be fetched otherwise:

scala-cli compile Sample.sc \
  --dependency "org::name::version,url=https://url-to-the-jar"

Note that --dependency is only meant as a convenience. You should favor adding dependencies in the sources themselves via using directives. However, the --dependency CLI option takes precedence over using directives, so it can be used to override a using directive, such as when you want to work with a different dependency version.

You can also add repositories on the command-line, via --repository or //> using repos

scala-cli compile Sample.sc \
  --dependency com.pany::util:33.1.0 --repo https://artifacts.pany.com/maven

Lastly, you can also add simple JAR files as dependencies with --jar:

scala-cli compile Sample.sc --jar /path/to/library.jar

Adding local JARs as dependencies

You can pass local JARs from the command line with the --extra-jar option:

scala-cli compile Sample.sc \
  --extra-jar "./path/to/custom.jar"

Local sources JARs can also be passed in a similar manner:

scala-cli compile Sample.sc \
  --extra-source-jar "./path/to/custom-sources.jar"

Both can be handled with the appropriate using directives, too:

//> using jar "./path/to/custom.jar"
//> using sourceJar "./path/to/custom-sources.jar"

caution

Local JARs with the *-sources.jar suffix are assumed to be sources JARs and are treated as such.