Upgrading

This page covers updating Elide, pinning the version a project uses, and what to change when you move to 1.6.

Update the installed binary

elide upgrade --check
elide upgrade
elide upgrade --channel release

Install method	Update with
Install script	`elide upgrade`; it keeps an installed Python component
Homebrew, apt, RPM, MSI	The package manager; see Packages & Installers
GitHub Actions	The `version` input of `setup-elide`; see Elide in CI

--channel is release or nightly; the default is the channel the running build came from. --force reinstalls the current version.

Pin a project

elide use 1.5.4

Elide 1.5.4 is already installed at /home/you/.local/share/elide/versions/1.5.4/bin/elide

elide use writes the version to .elideversion and installs it under ELIDE_HOME (default ~/.local/share/elide). Every elide command in that directory then runs the pinned version, downloading it on first use if needed:

elide info

Elide - putting the java back in javascript
Version: 1.5.4+20260921.44ff130047
Mode: release

Command	Effect
`elide use 1.5.4`	Pin a release and install it.
`elide use --channel nightly 20260921`	Pin the nightly build of that date.
`elide use 1.5.4+20260921`	Pin a nightly by its full tag.
`elide use --no-install 1.6.0`	Write `.elideversion` only.
`elide --use-version 1.5.4 run app.js`	Run an installed version once, without a pin.
`elide --ignore-version run app.js`	Run the binary on `PATH`, ignoring `.elideversion`.

elide --version always prints the binary on PATH; elide info prints the version that runs. Nightly tags have the form <version>+<YYYYMMDD>, for example 1.5.4+20260921; the list is on GitHub Releases.

To refuse versions outside a range instead of switching to one, set toolchain.engines in elide.pkl:

toolchain { engines { ["elide"] = ">=1.6.0" } }

elide build on an older binary then stops with Current version of Elide ('1.5.4') does not satisfy project requirements ('>=1.6.0'). See Toolchain.

Pin CI

Pin the version in the setup step, and commit .elideversion so local runs match:

- uses: elide-dev/setup-elide@v4.2.0
  with:
    version: 1.6.0
    channel: release

Any installed Elide downloads and runs the version in a committed .elideversion, so the workflow pin and the file must agree. For a nightly, pin the full dated tag.

Migrate from 1.5 to 1.6

Each row is a rename or removal from the 1.6.0 changelog, with the error 1.6 prints for old usage:

1.5	1.6	Old usage in 1.6
`elide manifest`	`elide project export`	elide manifest: removed; use `elide project export` instead (exit `2`)
`testing { coverage { … } }` in `elide.pkl`	Top-level `coverage { … }` block	Cannot find property `coverage` in object of type `elide.testing#Testing`.
`preview` release channel	`release` or `nightly`	`invalid value 'preview' for '--channel'` (exit `2`)
Python in every install	`elide setup python`, or `--with-python` on the install script	`Python support is not installed. Run 'elide setup python' to add it.`
JavaScript and Python share a context	`--interop` on programs that call between languages	`Cannot import 'mod.py': JavaScript entries run without Python. Re-run with --interop to use it.`
`http://` Maven repositories	`https://` URLs; plain HTTP is accepted only on loopback	`Maven repository 'plain' uses plain HTTP: http://example.com/maven`

Other 1.6 changes that can change results without an error:

Java compiles with --release, targeting jvm.target or Java 21.
A JavadocJar whose sources include Kotlin is generated by Dokka, which documents the Kotlin too; set generator = "javadoc" on it to keep the javadoc output of earlier releases. See JAR Assembly.
elide run and elide test exit with the program’s own exit code.
elide test stops discovery at a nested project; name its path to run it.
Source sets follow src/<set>/<language>, then src/<set>, then flat src or test; see Source Sets.

Patch releases within 1.6 only add elide.pkl properties. To keep a manifest on the 1.6.0 schema while running a newer Elide, amend the published schema; see elide.pkl Reference.