# Upgrading

> Update Elide, pin a project or CI job to one version with elide use and .elideversion, and the renames and removals to handle when moving from 1.5 to 1.6.

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

```bash
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](https://elide.help/docs/installation/packages) |
| GitHub Actions | The `version` input of `setup-elide`; see [Elide in CI](https://elide.help/docs/installation/ci-cd) |

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

## Pin a project

```bash
elide use 1.5.4
```

```text
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:

```bash
elide info
```

```text
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](https://github.com/elide-dev/elide/releases).

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

```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](https://elide.help/docs/elide-pkl-reference#toolchain).

## Pin CI

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

```yaml
- 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](https://elide.help/docs/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](https://elide.help/docs/toolchain/jvm/jar).
- `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](https://elide.help/docs/toolchain/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](https://elide.help/docs/elide-pkl-reference).