# Dependencies

> Declare Maven, npm and PyPI dependencies in elide.pkl and install Maven and npm packages with `elide install`: ecosystems, options and installed files.

Declare dependencies in `elide.pkl` and install them with `elide install`.

| Ecosystem | Enable with | Read from |
| --- | --- | --- |
| Maven | default | `elide.pkl`, or a `pom.xml` project selected with `-p` |
| npm | `--ecosystems=npm` | `elide.pkl` and `package.json` |
| PyPI | — | `dependencies.pypi` is accepted; `elide install` does not install it |

## Install dependencies

```bash
elide install                         # Maven
elide install --ecosystems=npm        # npm
elide install --ecosystems=maven,npm  # both
elide install --workspace             # every ecosystem the project declares
```

<img src="https://elide.help/assets/demos/install.gif" alt="Installing Maven and npm dependencies explicitly with Elide" width="1591" height="509" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

A `package.json` does not turn on npm; name every ecosystem CI needs. An unknown or unavailable ecosystem is a usage
error.

```mermaid
flowchart TD
  accTitle: What elide install does
  accDescr: elide install reads the dependencies in elide.pkl, or pom.xml with -p. With --fresh, or when the dependency list changed, it resolves the full graph from the repositories, downloads in parallel with checksums verified, and checks or pins each artifact's SHA-256. When the list is unchanged it downloads only files missing from disk, or is already up to date. Artifacts are linked from .dev/dependencies/m2 beside the classpath files. npm, when named, installs into .dev/dependencies/npm with aube-lock.yaml.
  start[elide install] --> read[Read elide.pkl,<br>or pom.xml with -p]
  read --> fresh{--fresh, or the<br>list changed?}
  fresh -->|yes| resolve[Resolve the graph<br>from the repositories]
  resolve --> fetch[Download in parallel,<br>checksums verified]
  fetch --> pin[Check or pin<br>each SHA-256]
  fresh -->|no| missing{Files missing?}
  missing -->|yes| fetch
  missing -->|no| done[Up to date]
  pin --> link[Link the Maven cache,<br>write classpaths]
  start -.->|--ecosystems=npm| npm[npm install,<br>aube-lock.yaml]
  class done,link accent
  class npm dim
```

Maven resolution is reused while the dependency list is unchanged: a missing file is restored on its own, and
every artifact's SHA-256 is pinned the first time it is seen and checked after that.

`elide install --fresh` resolves the graph again and downloads every required non-provided artifact again,
bypassing local artifact caches, worktree borrowing and HTTP conditional reuse. No additional `--no-cache`
flag is needed. It verifies the required artifacts without first deleting the installed repository.
A failed refresh leaves existing files in place. Matching JARs bundled with Elide are
installed locally rather than downloaded: hard links avoid extra copies where supported, with copying as a
fallback. JARs borrowed from mutable local repositories are copied into the project. Both remain usable after
the source distribution or cache is removed. `--direct` always requests copies.
Installation fails if a required artifact or provided resource is unreadable. Refresh does not prune unused
cached artifacts; the resolved graph and written classpaths determine which dependencies are used.

The committed binary lockfile also keeps a compact portable graph for immutable dependency versions. When the
manifest, roots, classifier requirements and platform match, a new checkout can restore that graph instead of analyzing
POMs again. Artifact SHA-256 pins remain stable across machines; distribution-provided bytes are checked against
the current distribution rather than pinned across Elide versions. Snapshots and open version selectors require
resolution rather than portable-graph reuse. Invalid or incompatible integrity lockfiles fail installation
rather than silently resetting pins. Concurrent saves merge independent pins and reject conflicting hashes.

In a Git worktree, missing pinned releases may be copied from neighboring worktrees, starting with the closest
commit history, including the main checkout. Copied bytes must match this project's lockfile before publication.
Other checkouts are read-only sources, their unpinned extras are not imported, and the current distribution
supplies its own JARs. A legacy shared dependency-directory link is migrated to a private copy before installation.
Warm installs with complete verified files do not scan neighboring worktrees. `--fresh` does not borrow artifacts
or reuse non-provided releases, even when their bytes match the lockfile hash.

## Declare dependencies

```pkl
amends "elide:project.pkl"

dependencies {
  maven {
    packages {
      "com.google.guava:guava:33.4.8-jre"
    }
  }
  npm {
    packages { "react@19.0.0" }
    devPackages { "typescript@5.6.2" }
  }
  pypi {
    packages { "requests>=2" }
    optionalPackages { ["dev"] { "pytest>=8" } }
  }
}
```

For a project with only a `pom.xml`, run `elide install -p .`; see [Maven Dependencies](https://elide.help/docs/toolchain/jvm/maven).

### Maven buckets

An entry is `group:artifact:version[:classifier]`, a `MavenPackageSpec`, a local JAR path, or a `project("name")`
reference. Workspace members can omit the version and take the root's
([Workspaces](https://elide.help/docs/elide-pkl-reference#workspaces)), and an entry declared beside a BOM (`group:bom:pom:version`) can
omit it and take the version the BOM lists. Conflicts resolve nearest-first, as in Maven, unless overridden by `resolutions`.

| Bucket | Applies to |
| --- | --- |
| `packages` | Compile and runtime classpaths of production sets. |
| `devPackages` | Development time only. |
| `modules` | `--module-path` for compiles, runs, tests and native images. |
| `compileOnly` | Compile classpath only. |
| `runtimeOnly` | Runtime classpath only. |
| `processors` | Annotation-processor path; see [Maven Dependencies](https://elide.help/docs/toolchain/jvm/maven#annotation-processors). |
| `testPackages` | Test sets, in addition to their production set's dependencies. |
| `androidTestPackages` | The `androidTest` source set: Android instrumented tests, which run on a device; never the host's test classpath. |
| `kotlinPlugins` | Kotlin compiler plugins; see [Kotlin Compiler](https://elide.help/docs/toolchain/jvm/kotlinc). |
| `exclusions` | Removed from resolution and every classpath. |
| `substitutions` | Local files replacing a coordinate on every classpath; see [reference](https://elide.help/docs/elide-pkl-reference#dependencies). |

### Maven version resolutions

Use `resolutions` to select an exact version wherever a module appears in the dependency graph:

```pkl
dependencies {
  maven {
    resolutions {
      ["org.example:library"] = "1.2.3"
    }
  }
}
```

Keys are `group:artifact`; the override applies to direct and transitive requests, including all
classifiers and packaging types, before their POMs are fetched. It does not add a dependency or
restore an excluded dependency. Version ranges, wildcards, `LATEST` and `RELEASE` are rejected.
Workspace members inherit root resolutions and can override them by key. Changing or removing a
resolution causes the dependency graph to be resolved again.

Spring Boot starters:

```pkl
dependencies {
  spring {
    version = "4.0.0"
    starter { "web"; "actuator" }
    testStarter { "test" }
  }
}
```

Each name becomes `org.springframework.boot:spring-boot-starter-<name>:<version>` in `packages` or `testPackages`.
Other Spring artifacts (`spring-boot-devtools`, `org.springframework:*`) go in `maven`; the two merge.
The [Spring Boot guide](https://elide.help/docs/toolchain/jvm/spring) shows a complete manifest for building, testing and packaging an application with Elide.

Android libraries, by family:

```pkl
dependencies {
  android {
    androidx { ["activity-compose"] = "1.9.3"; ["core-ktx"] = "1.15.0" }
    compose { bom = "2025.10.00"; modules { "ui"; "foundation"; "material3"; "ui-tooling" } }
    material = "1.12.0"
    playServices { ["location"] = "21.3.0" }
    test { runner = "1.6.2"; modules { "ext-junit" }; espresso { "core" } }
    robolectric = "4.16"
  }
}
```

| Family | Becomes |
| --- | --- |
| `androidx` | `androidx.<group>:<artifact>`: `core-ktx` is `androidx.core:core-ktx`; a nested group leads with its segments, `wear-compose-material3` is `androidx.wear.compose:compose-material3`. |
| `compose` | `androidx.compose.<group>:<module>`, versioned by the BOM (`bom`) or at one release (`version`). |
| `material` | `com.google.android.material:material`. |
| `playServices` | `com.google.android.gms:play-services-<name>`. |
| `test` | `androidx.test:runner` and the named AndroidX Test and Espresso libraries, at the release of `runner`, in `androidTestPackages`. |
| `robolectric` | `org.robolectric:robolectric` and the JUnit vintage engine `elide test` needs, in `testPackages`. |

A name its family does not know fails evaluation, naming the family and the name. Anything else goes in `maven`; the
two merge. Android archives need no `aar` packaging: it is read from the library's published metadata. See
[Android dependencies](https://elide.help/docs/toolchain/android/dependencies).

### Repositories

```pkl
dependencies {
  maven {
    repositories {
      ["company"] = "https://maven.example.com/releases"
      ["private"] {
        url = "https://packages.example.com/maven"
        credentials {
          username = read("env:MAVEN_USER")
          password = read("env:MAVEN_TOKEN")
        }
      }
    }
    localRepository = ".m2/repository"
  }
}
```

| Property | Meaning |
| --- | --- |
| `repositories[name].url` | Repository URL. |
| `repositories[name].credentials.username`, `.password` | Basic authentication. |
| `repositories[name].credentials.ntlmDomain`, `.ntlmWorkstation` | Either one selects NTLM. |
| `repositories[name].name`, `.description` | Display name and description. |
| `enableDefaultRepositories` | Include Maven Central (default `true`). |
| `localRepository` | Local Maven repository to resolve into. |

- Plain `http://` to anything but `127.0.0.0/8` fails with `Maven repository 'name' uses plain HTTP`.
  `elide build deps --allow-http-repositories` accepts it.
- `read("env:…")` needs `--allow-env`; see [Build Flags](https://elide.help/docs/toolchain/build-flags#environment-variables).
- With `enableDefaultRepositories`, Maven artifacts come from the `maven.pkg.st` proxy first, then Maven Central.
  A project declaring `android` or `dependencies.android` also resolves against Google's Maven repository:
  recognized public Google URLs try `gmaven.pkg.st` first, then their original endpoint. Custom mirrors and
  authenticated repositories keep their existing routes.
  pkg.st is enabled by default. `elide --no-pkgst build deps` or `ELIDE_PKGST=false` disables automatic proxy
  routing and every pkg.st feature below. Explicit global flags override the environment. The build-specific
  `--use-pkgst=false` (or `--no-use-pkgst`) also disables Maven's pkg.st features; it cannot override the global
  opt-out. Explicitly configured repository URLs remain in use, with ordinary Maven transport.
- Release POMs from `maven.pkg.st` and `gmaven.pkg.st` can arrive dictionary-compressed (RFC 9842 `dcz`) when the distribution ships the
  pinned Maven POM dictionary; Elide checks each decoded POM against the SHA-256 that pkg.st reports, and falls back
  to gzip or plain XML otherwise. `elide build deps --no-pkgst-dictionary` or `ELIDE_PKGST_DICTIONARY=false` turns
  this off. `ELIDE_PKGST_MAVEN_ORIGINS` (comma-separated origins, such as a staging mirror) extends the same
  negotiation beyond the built-in Central and Google Maven pkg.st origins. Google POMs use canonical XML;
  the current compact-descriptor client targets Maven Central's namespace only.
- pkg.st names the POMs a response leads to (parents, imported BOMs, direct dependencies), and Elide fetches them
  ahead of resolution within fixed item, byte and concurrency budgets. `elide build deps --pkgst-prefetch` (or
  `ELIDE_PKGST_PREFETCH=1` for `elide install`) also follows the parent and imported BOM POMs each downloaded POM
  declares; that is off by default.
- Each dependency's JAR starts downloading as soon as resolution reaches it, instead of after the whole graph is
  known. `ELIDE_PKGST_EARLY_ARTIFACTS=0` waits for the graph.
- A JAR from pkg.st larger than 32 MB (64 MB once the link measures fast) downloads as parallel byte ranges, joined
  in order and checked against the SHA-256 pkg.st reports. `ELIDE_PKGST_RANGES=0` downloads each JAR as one
  response.
- Descriptor mode defaults to `auto`: Elide fetches POMs' declared models from pkg.st as compact descriptors ahead
  of resolution over a WebSocket per worker (`wss://pkg.st/v1/descriptors:stream`), compressed with a Zstandard
  dictionary Elide ships, through the same proxy and TLS settings as other Maven requests. If the stream is
  unavailable, the rest of the run uses batches multiplexed over HTTP/2 with Brotli, Zstandard or gzip bodies;
  `--pkgst-descriptors=http` uses only those. A POM
  resolution needs before its descriptor has arrived is fetched as XML. Usable workspace and local POMs still take
  precedence, and a POM pkg.st cannot describe is fetched as XML and checked against its SHA-256.
- Fetched descriptors are kept in `.meta/pkgst-descriptors/` and reused on later runs; `--fresh` fetches them again.
  Keep that directory alongside the Maven repository when reusing CI caches.
- `--pkgst-descriptors=cached` reuses descriptors already on disk and never requests one. `--no-pkgst-descriptors` or
  `ELIDE_PKGST_DESCRIPTORS=off` uses XML only. `ELIDE_PKGST_DESCRIPTORS` takes the same values, and an explicit
  command-line mode wins over it.
- A repository's prefix catalog (`.meta/prefixes.txt`) from pkg.st is requested as a delta against the copy Elide
  already holds, or the copy it ships with: a few hundred bytes instead of the full catalog.
- When a file is already in the local repository during an ordinary install, Elide can send its SHA-256 and MD5 as
  `If-None-Match`. An unchanged file answers `304` and is kept; a changed or damaged one is downloaded again.
  `--fresh` omits these conditional validators and downloads the artifact body again.
- After an install, a two-line Maven cache report shows an efficiency meter and hits out of known cacheable
  fetches, followed by transfer savings, origin offload and local reuse. Wider terminals also show POM, JAR and
  metadata meters. `--verbose` retains the full breakdown with separate POM, artifact and other metadata rows.
  Successful GETs qualify when the response shows a cache hit or a usable
  cache lifetime; uncacheable responses, probes, unknown policies and failed requests are shown outside that
  denominator. Zero eligible fetches show `n/a`, not 100%. A local `304` saves client bytes but is not itself
  proof that the server avoided its upstream. Origin offload estimates describe known cacheable body bytes;
  unknown sizes are counted separately. Client savings show compression, local revalidation and descriptor
  replacement against identity-equivalent bytes, separately from local resolved-file reuse. These byte savings
  are estimates, and the report covers Maven rather than npm or Python traffic. `--quiet` omits it.
  The same breakdown is exported over OTLP: `elide.install.cache.eligible.requests` separates hits, misses,
  exclusions, unknown policy and failures by file kind; `elide.install.cache.eligible_hit_ratio` uses only known
  cacheable fetches. Byte counters separate origin offload from client transfer savings. The older overall
  response-hit metrics remain available for compatibility and use a different denominator.
- Maven metadata activity shares one progress row. Archive fetches take priority once downloads begin;
  auxiliary completion redraws are coalesced by the terminal ticker to avoid repainting for every POM.
- With [telemetry configured](https://elide.help/docs/opentelemetry/configuration), installs export aggregate resolution spans and a bounded
  sample of request detail. Successful pkg.st requests use the server's spans; client failures and retries have a
  separate detail budget. Later requests retain unsampled correlation context. Repository 404 probes are counted
  separately from genuine failures; a required dependency missing everywhere still fails the install. Decode and
  filesystem/hash processing times appear in the final correlated report, alongside bytes, caching and latency.
  Trace context (`traceparent`, `baggage`) is sent to pkg.st only. The final summary log and an optional aggregate
  transport diagnostic use the same configured OTLP pipeline; there are no per-probe logs.
- The Maven lockfile records the supplying repository for downloaded artifacts, without URL credentials or local
  filesystem paths. Repair and additional-classifier downloads prefer that supplier among your currently configured
  repositories, retaining upstream fallbacks and honoring `--no-pkgst`. Repository hints never add new endpoints or
  bypass SHA-256 verification. Existing locks remain readable and acquire hints as artifacts are resolved again.
- If pkg.st's descriptor service does not answer within five seconds, the run continues with XML. Maven still applies
  inheritance, interpolation, profiles, management and relocation to every model.

`elide build deps` runs the same resolution as a task and also takes `--offline`, `--allow-http-repositories`,
`--use-pkgst`, `--pkgst-dictionary`, `--pkgst-prefetch` and `--pkgst-descriptors`.

## Installed files

| Path | Contents |
| --- | --- |
| `.dev/dependencies/npm/node_modules` | npm packages; `node_modules` at the project root links here. |
| `aube-lock.yaml` | npm lockfile. |
| `.dev/dependencies/m2` | Links into the standard Maven cache. |
| `.dev/dependencies/m2/{compile,runtime,test,processors}.classpath` | Resolved classpaths; see [`elide classpath`](https://elide.help/docs/toolchain/source-sets#dependencies-and-classpaths). |

In a workspace, links are in the root's `.dev/dependencies/`; classpath files stay per project. There is no
cross-ecosystem lockfile; see [Build state](https://elide.help/docs/toolchain/build-tasks#build-state).

## Query dependency code

The experimental [dependency code index](https://elide.help/docs/toolchain/jvm/code-index) records types, members, and references from
resolved Maven JARs. Build it with `elide index build --layers=l1,l2,l3`, then use `resolve` to find which artifact
defines a class, `get` to inspect a type or member, and `references` to follow its code references. `used-by` finds
matching compiled local sources.

[OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) uses the same index for Java source transformations. Add recipe modules to
`devPackages`; they are development tools, separate from application dependencies.

## Implicit JVM libraries

- Java-only roots get no implicit Kotlin libraries, Metro runtime or Elide annotation API, even with a `kotlin` block.
- Kotlin roots get the libraries their `kotlin.features` enable.
- Kotlin roots also get the atomicfu runtime unless `kotlin.features.atomicfu = false`.
- Test sets get bundled JUnit unless `jvm.features.testing = false`; `elide test` then needs your own
  `junit-platform-console` for JVM tests.
- `dev.elide:elide-api` accepts `latest` as a version and resolves to the bundled artifact.
- Bundled libraries link Elide's own JARs, but their sources and Javadoc come from your repositories like any other
  dependency's, so `--with=sources` attaches `kotlin-stdlib` sources too. `elide-api` has none.

The full list, with versions: [JVM APIs](https://elide.help/docs/api-jvm#projects). To use [Elide annotations](https://elide.help/docs/api-jvm-annotations) from
Java:

```pkl
dependencies {
  maven {
    compileOnly { "dev.elide:elide-api:1.0.0" }
  }
}
```

npm specifics: [NPM Installer](https://elide.help/docs/toolchain/web/npm).

Studio session defaults also apply to the embedded npm installer: `ELIDE_PKGST=1`
enables the package CDN unless explicitly overridden by CLI flags. Requests to
the HTTPS `npm.pkg.st` origin carry a valid `ELIDE_STUDIO_SESSION_ID` for internal
correlation. Other registries receive no Studio session header. The native
installer retains unchanged package content when dependency versions drift;
Elide's `.dev/dependencies/npm` layout does not require an exact whole-project
input match to reuse those packages.
