Skip to main content

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 repositorykinddescription
centralMaven (root)Used by default, default repository for most Scala libraries
sonatype:snapshotsMaven (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:snapshotsMaven (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.
snapshotsMaven (root) and Maven S01 (root)An alias for sonatype:snapshots and sonatype-s01:snapshots.
ivy2localIvyLocal ivy repository, used to publish things locally (e.g. by publishLocal). Localized in <ivy-home>/local, usually <user-home>/.ivy/local.
m2LocalMavenLocal maven repository, localized in <user-home>/.m2/repository

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:

Main.scala
//> 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:

Main.scala
//> 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:

Main.scala
//> 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:

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

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:

Sample.sc
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.