skip to content

What is the system scope and <systemPath>, and why is it discouraged?

level: middleimportance: nice to knowfreq 25%

answer

  1. system = provided + explicit <systemPath>
  2. Maven does NOT search repos for it
  3. absolute path, often ${project.basedir}/lib/...
  4. not portable, no transitives, not packaged
  5. fix: mvn install:install-file or private repo

basics

~20 s

system scope behaves like provided but Maven does not search any repository; you must give an absolute path to the jar via <systemPath>. It is discouraged because it ties the build to a local file, breaks portability and reproducibility, and the jar is never packaged.

solid answer

~40 s

system is the odd scope: like provided it is on the compile and test classpaths, is not packaged, and is not transitive, but unlike every other scope Maven does not resolve it from a repository. You must supply <systemPath> pointing to a jar already present on the filesystem (typically via a property like ${project.basedir}/lib/foo.jar). It is discouraged because it makes builds non-portable and non-reproducible: the jar is not in any repository, CI or another developer may not have it at that path, version metadata and transitive dependencies are lost, and it will not be installed/deployed. The recommended alternatives are to install the jar into a repository (mvn install:install-file), publish it to a private repository (Nexus/Artifactory), or use a proper artifact coordinate. system survives mostly for legacy JDK tools.jar-style cases.

code

bash · 4 lines
bash
mvn install:install-file \
  -Dfile=legacy-sdk-1.0.jar \
  -DgroupId=com.acme -DartifactId=legacy-sdk \
  -Dversion=1.0 -Dpackaging=jar

go deeper

for a junior

Recognize that system requires a local file path and is rarely used.

for a middle

Explain systemPath, the portability problems, and that the jar is not packaged.

for a senior

Replace system dependencies with install-file or a private repo and justify why.

for a principal

Ban system scope in build policy and provide a repository-based onboarding path for third-party jars.

## What system is `system` is a classpath scope that, like `provided`, is available at **compile and test** time, is **not packaged**, and is **not transitive**. Its one unique trait: Maven does **not** look in the local or remote repository to find the jar. Instead you must explicitly tell it where the jar already lives on disk using **`<systemPath>`**, which must be an absolute path (commonly built from a property such as `${project.basedir}`). ```xml <dependency> <groupId>com.acme</groupId> <artifactId>legacy-sdk</artifactId> <version>1.0</version> <scope>system</scope> <systemPath>${project.basedir}/lib/legacy-sdk-1.0.jar</systemPath> </dependency> ``` ## Why it is discouraged - **Not portable / not reproducible.** The path must exist on every machine that builds the project — CI agents, teammates, release servers. A different layout breaks the build. - **No transitive metadata.** A system jar has no POM, so its own dependencies are unknown and not pulled in; you must add them by hand. - **Not deployed or installed.** It is excluded from your artifact, so consumers cannot get it either. - **Bypasses the repository model**, which is the whole point of Maven (versioning, caching, integrity). ## Better alternatives 1. **Install into the local repo** so it behaves like a normal dependency: ```bash mvn install:install-file \ -Dfile=legacy-sdk-1.0.jar \ -DgroupId=com.acme -DartifactId=legacy-sdk \ -Dversion=1.0 -Dpackaging=jar ``` 2. **Publish to a private repository** (Nexus, Artifactory, GitHub Packages) so CI and teammates resolve it normally. 3. Prefer an existing artifact coordinate if the library is on Maven Central. Historically `system` was used to reference the JDK's `tools.jar`; with modern JDKs even that need has largely disappeared.

  • What does <systemPath> point to?
    An absolute path (often via ${project.basedir}) to a jar already on the filesystem; Maven uses it directly instead of resolving from a repository.
  • What is the recommended replacement for a system dependency?
    Install the jar into a repository with mvn install:install-file or publish it to a private repository, then reference it by normal coordinates.

saying these in an interview costs you the question

  • Recommending system scope as a normal way to add local jars.
  • Forgetting that system jars are not packaged and have no transitive dependencies.
  • Using a relative systemPath and expecting it to work everywhere.

context

resolving links…