Lockfiles & CI Installs

Install the selected tools

Install the required plugins first. avm install installs all effective tool selections without changing pins. Unlocked installs include global selections; Java installs first when selected so Android can use a managed JDK.

avm plugin add node
avm plugin add java
avm install

Create a project lock

avm lock resolves releases and checksum metadata without installing runtimes. It writes sorted JSON atomically. It updates the nearest existing lock, or creates one next to the nearest project config, resolving selections from that directory.

Locks include project JSON and version-file selections, excluding personal global pins. By default only the host platform is included; --platform selects the explicit comma-separated set. Commit the resulting .avm.lock.

avm lock
avm lock --platform linux_amd64,darwin_arm64,windows_amd64

Frozen installation in CI

--frozen fails when the lock is missing, selected tool requests differ, or this platform has no locked asset. The installed native plugins must match the locked name and version; executable checksums are checked where recorded. All selections and plugin checks are validated before installation starts.

Use the same profile when creating and consuming the lock. Trust project aliases/env only after reviewing them. CI=true does not grant trust automatically.

avm --env ci lock
# Commit .avm.lock, then on the CI machine:
avm --env ci install --frozen
avm --env ci trust
avm --env ci run build

Updates and limits

With a valid lock, install, aliases, shims, env and which use its exact versions. Changed tool requests produce an error directing you to avm lock; run it explicitly to regenerate. Environment and alias edits alone do not invalidate the lock.

Node and Java support verified locked installs. Android and legacy asdf plugins support ordinary unlocked installs only. Plugin executable hashes are recorded for the host that creates the lock; other platforms warn and check plugin name/version when their hash is absent.

Existing installed runtimes are reused without scanning every file. New archives are verified before extraction, and AVM_ALLOW_UNVERIFIED cannot bypass a locked checksum. A later download failure may leave earlier successful installs in place.