`, using `moduleName` or the module holding the entrypoint.
- An entrypoint outside any module builds from the class path.
`moduleName` has no effect without modular JARs.
## Compile to WebAssembly
Declare a `WebImage` artifact or pass `--tool:wasm-gc` / `--tool:wasm-lm`; see [WebImage](https://elide.help/docs/toolchain/jvm/webimage).
To run existing WASM, see [WebAssembly](https://elide.help/docs/wasm). A native image can be the input to a
[container image](https://elide.help/docs/toolchain/jvm/containers).
---
# WebImage: JVM to WebAssembly
URL: https://elide.help/docs/toolchain/jvm/webimage
> Compile Java or Kotlin to a WebAssembly module and JavaScript loader with Elide's WebImage artifact: prerequisites, backends, hosts and compiler options.
A `WebImage` artifact compiles JVM bytecode to a JavaScript loader plus a WASM module. To run an existing WASM or
WASI binary, see [WebAssembly](https://elide.help/docs/wasm).
## Prerequisites
- [Binaryen](https://github.com/WebAssembly/binaryen) 119 or later, with `wasm-as` on `PATH` at build time.
- Code that meets the [Native Image requirements](https://elide.help/docs/toolchain/jvm/native-image): reachability metadata for reflection,
resources and proxies; no native dependencies.
- A host with WASM exception handling (and WASM GC for `wasm-gc`): Node.js 25+ or a current browser.
The deployed bundle needs neither Elide nor Binaryen.
## Build a complete project
```text
hello-wasm/
elide.pkl
src/main/java/Hello.java
```
```java
public class Hello {
public static void main(String[] args) {
System.out.println("Hello from WebImage");
}
}
```
```pkl
amends "elide:project.pkl"
import "elide:Jvm.pkl" as jvm
import "elide:NativeImage.pkl" as nativeImage
name = "hello-wasm"
artifacts {
["app-jar"] = new jvm.Jar {
sources { "main" }
}
["web"] = new nativeImage.WebImage {
from { "app-jar" }
name = "hello"
entrypoint = "Hello"
backend = "wasm-gc"
runtime = "generic"
autoRun = true
sourceMap = false
options {
optimization = "b"
}
}
}
```
```bash
elide build
```
Elide builds `app-jar`, then compiles it to `web`. `name` is the basename without `.js` or `.wasm`;
`optimization = "b"` is quick-build mode. Output goes to `.dev/artifacts/native-image/`:
| File | Purpose |
| --- | --- |
| `hello.js` | JavaScript loader and entrypoint. |
| `hello.js.wasm` | WASM module, loaded by `hello.js`. |
| `hello.js.wat` | WASM text form, for inspection. |
| `hello.js.map` | Source map for the loader, when `sourceMap = true`. |
Deploy `hello.js` and `hello.js.wasm` together. Kotlin and other JVM languages work the same way once packaged in a
JAR. A cache hit restores the whole bundle; turning `sourceMap` off removes the old `.js.map`.
## Choose a backend and host
| Property | Value | Meaning |
| --- | --- | --- |
| `backend` | `"wasm-gc"` (default) | Uses the host's WASM garbage collector. |
| `backend` | `"wasm-lm"` | Uses a garbage collector in linear memory; still needs the loader, not a WASI binary. |
| `runtime` | `"generic"` (default) | Loader supports browsers and Node. |
| `runtime` | `"browser"` | Loader specialized for browsers. |
| `runtime` | `"node"` | Loader specialized for Node-compatible APIs. |
| `autoRun` | `true` (default) | Starts the program when the loader loads; `false` leaves startup to the embedding page. |
| `sourceMap` | `false` (default) | `true` emits `hello.js.map`. |
An entrypoint is required even with `autoRun = false`. No `runtime` targets Cloudflare Workers, Fastly Compute or
WASI. Shared fields (`from`, `entrypoint`, `moduleName`, `options`) are listed under
[Native Image](https://elide.help/docs/toolchain/jvm/native-image#project-artifact). A WebImage cannot be the input to a
[container artifact](https://elide.help/docs/toolchain/jvm/containers).
Target guides: [Browser WASM](https://elide.help/docs/toolchain/web/wasm) and [Edge WASM](https://elide.help/docs/toolchain/edge/wasm).
### Run on a backend host
With `runtime = "generic"` or `"node"`:
```bash
node .dev/artifacts/native-image/hello.js
```
```text
Hello from WebImage
```
### Run in a browser
With `runtime = "browser"` or `"generic"` and `autoRun = true`, put this `index.html` in
`.dev/artifacts/native-image/`:
```html
Hello WebImage
Open the browser console to see the application output.
```
```bash
elide dev --no-tui --port 8000 .dev/artifacts/native-image
```
Open `http://localhost:8000/`; the output appears in the browser console. `file://` URLs do not work.
## Compiler options
The artifact's `options` block takes the [Native Image compiler options](https://elide.help/docs/toolchain/jvm/native-image#compiler-options);
which apply depends on the backend. Two cases specific to WebImage:
- `options.driverMode = "external"` uses `native-image` from `GRAALVM_HOME` or `JAVA_HOME`; that installation must
support the WebAssembly backends.
- `-H:EntryPointsConfig=config/entrypoints.json` in `options.flags` sets entry points; the path is relative to the
project root, and editing the file triggers a rebuild.
## Compile without a project manifest
```bash
elide javac -- -d classes src/main/java/Hello.java
elide native-image -- --tool:wasm-gc -Ob -cp classes -o hello Hello
elide native-image -- --tool:wasm-lm -Ob -cp classes -o hello-lm Hello
```
Bundles are written to the current directory. A `NativeImage` artifact with `--tool:wasm-gc` or `--tool:wasm-lm` in
`options.flags` still builds. To migrate it, change the class to `WebImage`, drop the flag and any `type`, and set
`backend`.
## Troubleshooting
| Symptom | Fix |
| --- | --- |
| `wasm-as` not found | Install Binaryen and put it on the build's `PATH`. |
| External driver rejects the WebAssembly backend | Point `GRAALVM_HOME` or `JAVA_HOME` at an installation whose `native-image` supports it, or use `driverMode = "embedded"`. |
| Conflicting raw options | Remove backend, runtime, startup and source-map flags; use the typed properties. Do not override `Backend` or the launcher property. |
| Host rejects WASM instructions | Use a host with exception handling and, for `wasm-gc`, WASM GC. |
| Browser cannot load the module | Serve loader and module together over HTTP; check the requested URL. |
| `elide run hello.js.wasm` reports missing imports | Run `hello.js` instead; the module needs its loader. |
---
# JVM containers
URL: https://elide.help/docs/toolchain/jvm/containers
> Build a Docker or OCI container image from a JAR or native executable as an Elide project artifact, loaded into the local daemon or written as a tarball.
Container images are project artifacts; there is no `elide` container subcommand.
## Declare an image
```pkl
amends "elide:project.pkl"
import "elide:Jvm.pkl" as Jvm
import "elide:Container.pkl" as Container
artifacts {
["app"] = new Jvm.Jar {
sources { "main" }
}
["image"] = new Container.ContainerImage {
from { "app" }
image = "my-app"
base = "eclipse-temurin:25-jre"
tags { "latest" }
output = "daemon"
}
}
```
```bash
elide build
```
## Fields
| Property | Values | Default |
| --- | --- | --- |
| `from` | Exactly one `Jvm.Jar` (JVM image) or `NativeImage` (executable image). | — |
| `image` | Target image coordinate. | — |
| `base` | Base image coordinate. | — |
| `tags` | Image tags. | none |
| `output` | `"daemon"` (local Docker daemon) or `"tarball"` (importable archive). | `"daemon"` |
| `format` | `"docker"` (manifest v2) or `"oci"`. | `"docker"` |
| `dependsOn` | Artifacts to build first. | none |
An empty `from`, two distinct entries, or any other artifact type (including a `WebImage`) fails before the build.
---
# Python toolchain
URL: https://elide.help/docs/python-toolchain
> What Elide's Python toolchain covers in 1.6.0: the optional Python component, running scripts and modules, pyproject.toml entry points, virtual environments, tests, and what is not available.
Python support is experimental in 1.6.0. Elide runs Python 3.13 with its standard library; it does not install PyPI
packages, format Python, or run Python tests under `elide test`.
| Task | Command | Status |
| --- | --- | --- |
| Add Python to an install | `elide setup python` | Available |
| Run a script, `-c` or `-m` | `elide python ...`, `elide run app.py` | Available |
| Run a `pyproject.toml` entry point | `elide run NAME` | Available |
| Use packages from a virtual environment | `VIRTUAL_ENV=.venv elide python app.py` | Available |
| Run unittest or pytest | `elide python -m unittest`, `elide python -m pytest` | Available |
| Install PyPI packages | `elide install` | Not available; use a virtual environment |
| Discover Python tests | `elide test` | Not available |
| Format, LSP, `elide init` template | | Not available |
## Add Python
Python is an optional component:
```bash
elide setup python
```
Without it, Python commands print `Python support is not installed. Run 'elide setup python' to add it.` and exit `2`.
See [Python with Elide](https://elide.help/docs/python) for channels and package-manager installs.
## Run Python
`elide python` takes the same arguments as `python`; `elide run` and a bare `elide app.py` run `.py` files too:
```bash
elide python app.py --name Elide
elide python -m json.tool input.json
elide run app.py
```
Interpreter flags (`-I`, `-B`, `-u`, `-W`, ...) are listed in [Python with Elide](https://elide.help/docs/python#interpreter-options).
## Run project scripts
`elide run NAME` runs a `[project.scripts]` entry point from the `pyproject.toml` in the current directory. No
`elide.pkl` is needed.
```toml
# pyproject.toml
[project]
name = "greet"
version = "0.1.0"
requires-python = ">=3.13"
[project.scripts]
greet = "greet.cli:main"
```
```python
# greet/cli.py
import sys
def greeting(name: str) -> str:
return f"Hello, {name}!"
def main() -> int:
print(greeting(sys.argv[1] if len(sys.argv) > 1 else "world"))
return 0
```
```bash
elide run greet Elide
```
```terminaloutput
Hello, Elide!
```
`elide greet Elide` does the same. Arguments after the name go to `sys.argv`, and the function's integer return value
is the exit code. A file named `greet`, an `elide.pkl` script or a `package.json` script of the same name wins; see
[Project setup](https://elide.help/docs/projects#add-a-script).
## Packages
`elide install` installs no PyPI packages, and `elide install --ecosystems=pypi` exits `2`. Install packages into a
Python 3.13 virtual environment with another tool and point Elide at it with `VIRTUAL_ENV`; see
[Packages and virtual environments](https://elide.help/docs/python-packages).
## Tests
Run unittest or pytest through `elide python -m`; see [Python tests](https://elide.help/docs/python-testing). `elide test` runs JavaScript,
TypeScript and JUnit tests only.
## Samples
- [Python calling JavaScript](https://elide.help/docs/code-samples#python-calling-javascript)
- [JavaScript importing Python](https://elide.help/docs/code-samples#javascript-importing-python)
- [Python script](https://elide.help/docs/code-samples#python-script)
`elide init` has no Python template.
## Known limitations
- **C extensions**: some C extension modules do not load.
- **pip**: not bundled; `elide python -m pip` fails with `No module named pip`.
- More: [Python with Elide](https://elide.help/docs/python#known-limitations).
---
# Packages and virtual environments
URL: https://elide.help/docs/python-packages
> Use third-party Python packages with Elide: create a Python 3.13 virtual environment, install packages with uv, and set VIRTUAL_ENV so Elide imports them.
Elide does not install PyPI packages in 1.6.0. It imports packages from a Python 3.13 virtual environment named by
`VIRTUAL_ENV`.
| Source | What Elide does |
| --- | --- |
| `pyproject.toml` `[project] dependencies` | Nothing; `[project.scripts]` entry points run with `elide run` ([Python Toolchain](https://elide.help/docs/python-toolchain#run-project-scripts)) |
| `elide.pkl` `dependencies.pypi` | Accepts the declaration; `elide install` skips it ([reference](https://elide.help/docs/elide-pkl-reference#dependencies)) |
| `requirements.txt` | Nothing |
| `$VIRTUAL_ENV/lib/python3.13/site-packages` | Adds it to `sys.path` |
`elide install --ecosystems=pypi` prints `elide install: pypi installs are not available in this build` and exits `2`.
## Create a virtual environment
Create the environment with a Python 3.13 tool. With [uv](https://docs.astral.sh/uv/):
```bash
uv venv --python 3.13 .venv
uv pip install --python .venv/bin/python attrs
```
The environment's own interpreter is only used to install packages; Elide runs the code.
## Use it
```python
# app.py
import attrs
@attrs.define
class Point:
x: int
y: int
print(Point(1, 2))
```
```bash
VIRTUAL_ENV=.venv elide python app.py
```
```terminaloutput
Point(x=1, y=2)
```
Activating the environment sets `VIRTUAL_ENV` too:
```bash
source .venv/bin/activate
elide run app.py
```
Without `VIRTUAL_ENV`, the import fails with `ModuleNotFoundError: No module named 'attrs'`.
## Limits
- The environment must be Python 3.13: Elide reads `lib/python3.13/site-packages`.
- Pure-Python packages work. Some C extension modules do not load.
- pip is not bundled, so `elide python -m pip` fails; install with the environment's own tools.
---
# Python tests
URL: https://elide.help/docs/python-testing
> Run Python tests on Elide with unittest from the standard library or pytest from a virtual environment; `elide test` does not discover Python tests in 1.6.0.
`elide test` does not discover Python tests in 1.6.0; in a Python-only directory it prints `No tests found.` and exits
`0`. Run the test runner as a module instead. The exit code is the runner's, so a failing test fails the command.
The examples test this module:
```python
# greet/cli.py
import sys
def greeting(name: str) -> str:
return f"Hello, {name}!"
def main() -> int:
print(greeting(sys.argv[1] if len(sys.argv) > 1 else "world"))
return 0
```
`greet/` and `tests/` each contain an empty `__init__.py`.
## unittest
unittest ships with the standard library:
```python
# tests/test_cli.py
import unittest
from greet.cli import greeting
class GreetingTest(unittest.TestCase):
def test_names_the_caller(self):
self.assertEqual(greeting("Elide"), "Hello, Elide!")
```
```bash
elide python -m unittest discover -s tests -t .
```
```terminaloutput
.
----------------------------------------------------------------------
Ran 1 test in 0.001s
OK
```
## pytest
Install pytest into a Python 3.13 virtual environment ([Packages and virtual environments](https://elide.help/docs/python-packages)), then run
it with `VIRTUAL_ENV` set:
```bash
uv venv --python 3.13 .venv
uv pip install --python .venv/bin/python pytest
```
```python
# tests/test_greeting.py
from greet.cli import greeting
def test_default_name():
assert greeting("world") == "Hello, world!"
```
```bash
VIRTUAL_ENV=.venv elide python -m pytest -q
```
pytest collects both files and ends with:
```terminaloutput
2 passed in 0.03s
```
## In CI
Add the Python component after installing Elide (`elide setup python`), then run the same commands; see
[Continuous Integration](https://elide.help/docs/installation/ci-cd#example-workflow).
---
# Web toolchain
URL: https://elide.help/docs/toolchain/web
> Run JavaScript and TypeScript with Elide, serve files during development, process web assets, install npm packages and configure web builds in elide.pkl.
Run, serve, build and install dependencies for JavaScript and TypeScript projects.
## Run JavaScript and TypeScript
```bash
elide run app.js
elide run app.ts
```
TypeScript types are stripped. `.mjs`, `.cjs`, `.mts` and `.cts` also work.
## Serve and develop
```bash
elide serve dist # serve a directory on 127.0.0.1:8080
elide dev public # dev server on 127.0.0.1:3000; pages reload when files change
```
Page reload applies to directories, not to a script passed to `elide dev`. `--host` and `--port` set the address,
`--no-watch` turns off watching, and `--no-tui` prints plain logs. More, including `--contexts`:
[Development Server](https://elide.help/docs/dev-server).
## Process assets
No manifest needed:
```bash
elide web build app.ts --out dist # JavaScript
elide web build page.md --out dist # HTML
elide web build style.css --out dist # CSS
```
Several sources and shell globs are accepted.
## Install npm packages
```bash
elide install --ecosystems=npm
```
See [NPM Installer](https://elide.help/docs/toolchain/web/npm).
## Manifest settings
```pkl
web {
minifyHtml = true
css {
minify = true
targets {
new { browser = "chrome"; version = "120" }
new { browser = "safari" }
}
}
}
javascript {
ecma = "stable"
}
```
| Property | Meaning | Default |
| --- | --- | --- |
| `web.minifyHtml` | Minify HTML, including inline scripts and styles. | `true` |
| `web.css.minify` | Minify CSS. | `true` |
| `web.css.targets` | CSS browser targets: `browser` (`chrome`, `firefox`, `safari`, `edge`, `opera` or other) and optional `version`. | none |
| `web.browsers` | Browser targets for all outputs; `css.targets` overrides it for CSS. | none |
| `javascript.ecma` | Declared ECMAScript edition: a year `2015` … `2025`, `"stable"` or `"latest"`. `elide project info` shows it; it does not change which syntax runs or how code is built ([JavaScript language](https://elide.help/docs/javascript-language)). | `"stable"` |
## Project builds
To build a site with `elide build`, declare a [static-site artifact](https://elide.help/docs/toolchain/web/static-site). To compile Java or
Kotlin for the browser, see [Browser WASM](https://elide.help/docs/toolchain/web/wasm).
---
# npm installer
URL: https://elide.help/docs/toolchain/web/npm
> Install npm packages with `elide install --ecosystems=npm`: Elide reads package.json and the npm block in elide.pkl, and links packages into node_modules.
Elide installs npm packages and links them into the project's `node_modules`.
```bash
elide install --ecosystems=npm
```
npm is opt-in; a bare `elide install` installs Maven only. Elide reads `package.json` and the `npm` block in
`elide.pkl`:
```pkl
amends "elide:project.pkl"
dependencies {
npm {
packages {
"react@19.0.0"
}
devPackages {
"typescript@5.6.2"
}
}
}
```
| Property | Meaning |
| --- | --- |
| `packages` | `name@version` or `@scope/name@version`. |
| `devPackages` | Development-time packages. |
Packages go to `.dev/dependencies/npm/node_modules`, linked from `node_modules` at the project root. Resolution is
recorded in `aube-lock.yaml`. Ecosystem selection and shared options: [Dependencies](https://elide.help/docs/toolchain/dependencies).
---
# Static sites
URL: https://elide.help/docs/toolchain/web/static-site
> Build a static site with Elide's StaticSite artifact: render Markdown, process scripts and stylesheets, compress images and copy other files.
A `StaticSite` artifact renders Markdown, processes scripts and stylesheets, compresses images and copies everything
else.
```pkl
amends "elide:project.pkl"
import "elide:Web.pkl" as Web
artifacts {
["site"] = new Web.StaticSite {
srcs = "site"
domain = "example.com"
stylesheets { "site/theme.css" }
hosting = "github-pages"
}
}
```
```bash
elide build
```
## Fields
| Property | Meaning | Default |
| --- | --- | --- |
| `srcs` | Source directory, relative to the project. | — |
| `domain` | Production domain. | — |
| `preview` | Preview domain; informational. | — |
| `prefix` | Mount path for links and assets; must end with `/`. | `"/"` |
| `assets` | Public asset path. | `"_/assets"` |
| `stylesheets` | Added to every page, besides those in its frontmatter. | none |
| `scripts` | Added to every page, besides those in its frontmatter. | none |
| `rewriteLinks` | Rewrite relative Markdown links against `prefix`. | `true` |
| `hosting` | `"workers"` or `"github-pages"`; informational, the build does not publish. | — |
| `dependsOn` | Artifacts to build first. | none |
Minification and browser targets come from the `web` block ([Web Toolchain](https://elide.help/docs/toolchain/web#manifest-settings)).
Without image codecs, the build warns once and copies images unchanged.
## Samples
Start from a template:
```bash
elide init --template web-simple # static site
elide init --template web-demo # static site with TypeScript and Markdown
```
---
# Browser WASM
URL: https://elide.help/docs/toolchain/web/wasm
> Compile Java or Kotlin to WasmGC with Elide: build a WebAssembly module and JavaScript loader, load it from a web page, and check browser support.
A [WebImage](https://elide.help/docs/toolchain/jvm/webimage) artifact with `backend = "wasm-gc"` compiles Java or Kotlin to WasmGC: a
WebAssembly module whose objects live in the browser's garbage-collected heap, plus a JavaScript loader that fetches
and starts it. To run an existing `.wasm` file with Elide, see [WebAssembly](https://elide.help/docs/wasm).
## Prerequisites
- [Binaryen](https://github.com/WebAssembly/binaryen) 119 or later, with `wasm-as` on `PATH` at build time.
- Code that meets the [Native Image requirements](https://elide.help/docs/toolchain/jvm/native-image): reachability metadata for reflection,
resources and proxies; no native dependencies.
## Build
```text
hello-wasm/
elide.pkl
src/main/java/Hello.java
```
```java
public class Hello {
public static void main(String[] args) {
System.out.println("Hello from WasmGC");
}
}
```
```pkl
amends "elide:project.pkl"
import "elide:Jvm.pkl" as jvm
import "elide:NativeImage.pkl" as nativeImage
name = "hello-wasm"
artifacts {
["app-jar"] = new jvm.Jar {
sources { "main" }
}
["web"] = new nativeImage.WebImage {
from { "app-jar" }
name = "hello"
entrypoint = "Hello"
backend = "wasm-gc"
runtime = "browser"
}
}
```
```bash
elide build
```
Output goes to `.dev/artifacts/native-image/`:
| File | Deploy | Hello-world size |
| --- | --- | --- |
| `hello.js` | Yes: the loader. | 110 KB |
| `hello.js.wasm` | Yes: the module. | 1.3 MB (480 KB gzipped) |
| `hello.js.wat` | No: text form, for inspection. | 32 MB |
| `hello.js.map` | Optional: emitted with `sourceMap = true`. | |
| Property | Browser value |
| --- | --- |
| `backend` | `"wasm-gc"` (the default). |
| `runtime` | `"browser"`, or `"generic"` to keep Node support in the same loader. |
| `autoRun` | `true` (default) runs `main` when `hello.js` loads. |
Other properties and compiler options: [WebImage](https://elide.help/docs/toolchain/jvm/webimage#choose-a-backend-and-host).
## Load it in a page
Put `index.html` next to the bundle:
```html
Hello WasmGC
```
```bash
elide dev --no-tui --port 8000 .dev/artifacts/native-image
```
Open `http://localhost:8000/`; `Hello from WasmGC` appears in the browser console.
- The loader requests the module at its own URL plus `.wasm`, so keep `hello.js` and `hello.js.wasm` in the same
directory.
- Load it with a classic `
## Common commands
```bash
elide run app.ts # run a file
elide python script.py # run Python with CPython-style arguments
elide repl # interactive REPL
elide init # start a new project from a template
elide adopt # migrate an existing project with an AI coding agent
elide install # install Maven dependencies
elide install --ecosystems=npm # install npm dependencies
elide build # build the project
elide test # run tests
elide format -- src # format Java and Kotlin sources
elide serve --no-tui ./dist # serve a directory over HTTP
elide --help-all # every command and flag
elide help 
`elide info` lists the available languages, including `python` when it is installed. If the shell cannot find
`elide`, open a new terminal or add the install's `bin` folder to `PATH`.
## System requirements
| Platform | Architecture | Minimum | Python component |
| --- | --- | --- | --- |
| Linux | `amd64` | glibc 2.34, kernel 4.18 | Yes |
| Linux | `arm64` | glibc 2.34, kernel 4.18 | Yes |
| macOS | Apple Silicon (`arm64`) | macOS 11 | Yes |
| Windows | `amd64` | — | Yes |
- Ubuntu 22.04, Debian 12, RHEL 9, Fedora 35 and later meet the glibc floor. On older distributions (for example
Debian 11) `elide` exits with `version GLIBC_2.34 not found`; use a [container image](https://elide.help/docs/installation/containers)
there.
- Alpine and other musl-based distributions are not supported (`exec elide: no such file or directory`).
- Intel Macs are not supported.
Check your glibc with:
```bash
ldd --version | head -1
```
---
# Packages and installers
URL: https://elide.help/docs/installation/packages
> Install Elide with Homebrew, apt, RPM, or the macOS and Windows installers, upgrade through the package manager, and verify checksums and signatures.
Upgrade these installs through their package manager, not `elide upgrade`. Only Homebrew includes Python; see
[Installation](https://elide.help/docs/installation#python).
## Homebrew
```bash
brew install elide-dev/elide/elide
brew upgrade elide
```
The [`elide-dev/homebrew-elide`](https://github.com/elide-dev/homebrew-elide) tap tracks `nightly` on macOS (Apple
Silicon) and Linux (`amd64`, `arm64`).
## Debian and Ubuntu (apt)
```bash
curl -fsSL https://keys.elide.dev/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/elide.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/elide.gpg]" \
"https://dl.elide.dev release main" | sudo tee /etc/apt/sources.list.d/elide.list
sudo apt update && sudo apt install elide
```
Replace `release` with `nightly` for daily builds. Upgrade with `sudo apt update && sudo apt upgrade elide`. The
package installs into `/opt/elide/
Python needs the Python component (`elide setup python`):
```python
# hello.py
print("Hello from Python!")
```
```bash
elide python hello.py
```
```terminaloutput
Hello from Python!
```
Kotlin and Java files run the same way:
```kotlin
// hello.kt
fun main() {
println("Hello from Kotlin!")
}
```
```bash
elide run hello.kt
```
```terminaloutput
Hello from Kotlin!
```
In the project, `elide run` with no file builds and runs `jvm.main`, which prints `Hello Elide!`.
### Executable scripts
Start a file with `#!/usr/bin/env elide` and mark it executable. Arguments reach `process.argv` or `sys.argv`:
```ts
#!/usr/bin/env elide
const n: number = 42;
console.log(`ts ${n}`, process.argv.slice(2).join(" "));
```
```bash
chmod +x hello.ts
./hello.ts --flag x
```
```terminaloutput
ts 42 --flag x
```
The same line works for `.js`, `.mjs` and `.py` files. A file without an extension runs as JavaScript.
## Add a dependency
Declare packages in `elide.pkl`:
```pkl
dependencies {
maven {
packages { "com.google.guava:guava:33.4.8-jre" }
}
npm {
packages { "zod@3.25.76" }
}
}
```
```bash
elide install # Maven
elide install --ecosystems=maven,npm # Maven and npm
```
npm packages install into `node_modules`, and npm also reads `package.json`. `elide install` does not install `pypi`
packages. See [Dependencies](https://elide.help/docs/toolchain/dependencies).
## Test
```bash
elide test
```
```terminaloutput
com.example.HelloTest
✓ testGreeting() [15ms]
1 pass
0 skip
0 fail
Ran one test across one file. (0.67s)
```
`elide test` also runs JavaScript and TypeScript `node:test` files; see [Testing](https://elide.help/docs/toolchain/testing).
## Build
```bash
elide build
```
Outputs and build state go in `.dev/`. `elide build --inspect` lists the tasks and their options; see
[Build Tasks](https://elide.help/docs/toolchain/build-tasks).
## Next steps
- Languages: [JavaScript and TypeScript](https://elide.help/docs/web), [Python](https://elide.help/docs/python), [Java and Kotlin](https://elide.help/docs/jvm),
[WebAssembly](https://elide.help/docs/wasm).
- [Toolchain](https://elide.help/docs/toolchain): building, testing, formatting and packaging.
- [Project setup](https://elide.help/docs/projects): scripts, workspaces and pinning the Elide version.
- [Development Server](https://elide.help/docs/dev-server): `elide dev` serves a directory or server script with page reload.
- [Code Samples](https://elide.help/docs/code-samples): one-file examples with their expected output.
---
# JavaScript and TypeScript with Elide
URL: https://elide.help/docs/web
> Run JavaScript and TypeScript with Elide without a compile step or tsconfig.json: CommonJS and ES modules, npm packages, node:test tests and servers.
Elide runs JavaScript and TypeScript directly, with CommonJS, ES modules, and a subset of the Node and Web APIs.
> [!TIP] TypeScript runs as written
> No compile step and no `tsconfig.json`: `elide app.ts` runs the file.
```bash
elide run app.js
elide run app.ts
elide app.ts
elide run -s 'console.log(1 + 1)'
```
Extensions: `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, `.tsx`. JSX and TSX are transformed; install the
runtime they import, such as `react/jsx-runtime`. Elide provides no UI framework or DOM.
## npm packages
Declare dependencies in `package.json`. Plain `elide install` skips npm, so pass `--ecosystems=npm`:
```json
{
"type": "module",
"dependencies": { "zod": "3.24.1" }
}
```
```ts
// app.ts
import { z } from "zod";
const User = z.object({ name: z.string() });
console.log(`Hello, ${User.parse({ name: "Ada" }).name}!`);
```
```bash
elide install --ecosystems=npm
elide run app.ts
```
The general commands run `.py` files with the same `sys.argv`:
```bash
elide app.py
elide run app.py
elide -l python -s 'print(1 + 1)'
```
### Interpreter options
Put these before the script, `-c`, or `-m`. `elide --help-all` lists them under "Python interpreter options".
| Flag | Effect |
| --- | --- |
| `-c CMD` | Run `CMD` as the program; trailing tokens become `sys.argv[1:]`. |
| `-m MODULE` | Run a library module as `__main__`. |
| `-s` | Don't add the user site directory to `sys.path`. |
| `-I` | Isolated mode. |
| `-E` | Ignore `PYTHON*` environment variables. |
| `-S` | Don't `import site` on startup. |
| `-P` | Don't prepend a potentially unsafe path to `sys.path`. |
| `-B` | Don't write bytecode files. |
| `-u` | Unbuffered standard output and error. |
| `-O` | Optimization level; repeat for `-OO`. |
| `-b` | Warn on `bytes`/`str` comparisons; repeat to raise errors. |
| `-W ARG` | Warning control; repeatable. |
| `-x` | Accepted for compatibility; no effect. |
Two flags are on by default: `-S`, because Elide builds `sys.path` itself and skips `site` for startup time, and
`-B`. `sys.flags` reports both. To import `site` (`.pth` files, `sitecustomize`), pass
`-X polyglot.python.NoSiteFlag=false`; to write bytecode, pass `-X polyglot.python.DontWriteBytecodeFlag=false`.
## Standard library
The standard library includes `json`, `pathlib`, `sqlite3`, `ssl`, `zlib`, and `ctypes`. `bz2` and `lzma` need no
system `libbz2` or `liblzma`. For the database drivers Elide includes, see [Databases](https://elide.help/docs/api-database).
## JavaScript interop
With `--interop`, Python evaluates JavaScript through the built-in `elide` module:
```python
# sum.py
from elide import js
print(js("[1, 2, 3].reduce((a, b) => a + b, 0)"))
```
```bash
elide --interop python sum.py
```
JavaScript and TypeScript import a Python module's default export:
```javascript
// main.mjs
import mod from "./mod.py";
console.log(mod.hello());
```
```bash
elide --interop run main.mjs
```
Without `--interop`, these calls fail. See [Languages and Interop](https://elide.help/docs/languages).
## Third-party packages
Elide does not install PyPI packages: `elide install` skips `dependencies.pypi`, and
`elide install --ecosystems=pypi` exits `2`. To load packages from a Python 3.13 virtual environment, set
`VIRTUAL_ENV`:
```bash
export VIRTUAL_ENV=/path/to/venv
elide python app.py
```
Elide reads the environment's `lib/python3.13/site-packages`.
See [Packages and virtual environments](https://elide.help/docs/python-packages); for unittest and pytest, see
[Python tests](https://elide.help/docs/python-testing).
## Tracing and metrics
The `opentelemetry` API and `logging` export traces, metrics, and logs through Elide, with no SDK installed; see
[OpenTelemetry in Python](https://elide.help/docs/opentelemetry/python).
## Known limitations
- **C extensions**: some C extension modules do not load.
- **macOS**: native module isolation is not available.
- **WebAssembly SIMD**: installing Python disables it; see [WebAssembly with Elide](https://elide.help/docs/wasm#limits).
- **CPython differences**: some edge cases behave differently from CPython 3.13; see the
[Compatibility Matrix](https://elide.help/docs/compatibility).
## Samples
- [Python calling JavaScript](https://elide.help/docs/code-samples#python-calling-javascript)
- [JavaScript importing Python](https://elide.help/docs/code-samples#javascript-importing-python)
- [Python script](https://elide.help/docs/code-samples#python-script)
---
# Java and Kotlin with Elide
URL: https://elide.help/docs/jvm
> Run Java and Kotlin source files with Elide, use the bundled JDK 25 and Kotlin tools, resolve Maven dependencies, and build and test a project.
Elide compiles, formats, builds, and tests Java (up to JDK 25) and Kotlin (2.5.0-Beta1), and resolves Maven
dependencies.
> [!TIP] No JDK to install
> The JDK and Kotlin tools ship with Elide; no separate JDK, Kotlin compiler or build tool is needed.
## Run a source file
A file with a `main` entrypoint compiles and runs directly:
```bash
elide run Hello.java
elide run Hello.kt
```
## Use individual tools
`elide java`, `elide javac`, `elide kotlinc`, and `elide jar` work like the tools they name. Arguments go after `--`:
```bash
elide javac -- -d target src/main/java/app/Main.java
elide kotlinc -- -d target src/main/kotlin/app/Main.kt
elide java -- -cp target app.Main
```
`elide format` formats Java with Google Java Format and Kotlin with ktfmt:
```bash
elide format -- src # rewrite files
elide format --list-files -- --dry-run src # list files that would change; exit 1 if any
```
## Start a project
```bash
elide init --plain --skip-defaults --template java
```
| Template | Creates |
| --- | --- |
| `java` | A Java project. |
| `ktjvm` | A Kotlin project. |
| `workspace` | A Kotlin library and an app that depends on it. |
To migrate a Maven or Gradle project, `elide adopt` runs an AI coding agent; see
[Adopt an Existing Project](https://elide.help/docs/toolchain/usage/adopt).
## Build a project
```bash
elide install # resolve Maven dependencies
elide build # compile and assemble artifacts
elide test # run JUnit tests
elide run # run the project's main class
```
`elide build --inspect` lists the project's tasks. Manifest: [Project setup](https://elide.help/docs/projects). Compiler and packaging
options: [JVM Toolchain](https://elide.help/docs/toolchain/jvm).
## What programs can use
The JDK, the Kotlin standard library, bundled kotlinx libraries, JUnit for tests, and Elide's annotations; there is no
Elide runtime API and no calls into JavaScript or Python. See [JVM APIs](https://elide.help/docs/api-jvm). For a database, add its JDBC driver
as a Maven dependency ([Databases](https://elide.help/docs/api-database#other-languages)); to share a library, see
[Maven publishing](https://elide.help/docs/toolchain/jvm/publishing).
## Tracing and metrics
Java and Kotlin programs that Elide runs get no OpenTelemetry API, agent, or trace context from Elide. Add the
OpenTelemetry Java SDK or agent to the program as on any JVM. `elide build` and `elide test` still export their own
spans; see [OpenTelemetry](https://elide.help/docs/opentelemetry#languages).
## Rewrite and inspect code
For projects with `elide.pkl`, [OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) previews and applies Java recipes, and the
[dependency code index](https://elide.help/docs/toolchain/jvm/code-index) finds class origins, inspects members, and queries compiled
Java and Kotlin references. Both are experimental in 1.6.0.
## Samples
- [Java records and streams](https://elide.help/docs/code-samples#java-records-and-streams)
- [Kotlin collections](https://elide.help/docs/code-samples#kotlin-collections)
- [Kotlin tests](https://elide.help/docs/code-samples#kotlin-tests)
- [Kotlin coroutines](https://elide.help/docs/code-samples#kotlin-coroutines)
- [Java with a Maven dependency](https://elide.help/docs/code-samples#java-with-a-maven-dependency)
Start from a template:
```bash
elide init --template java # Java app with a JUnit test
elide init --template ktjvm # Kotlin app with a test
elide init --template workspace # Kotlin library and app in one workspace
```
---
# WebAssembly with Elide
URL: https://elide.help/docs/wasm
> Run WASI command modules with Elide, map host directories, load WebAssembly libraries from JavaScript and TypeScript, and check supported proposals.
WebAssembly support is experimental in 1.6.0.
| You have | Use | Result |
| --- | --- | --- |
| A WASI command | `elide run app.wasm` | Runs the module with WASI Preview 1 imports. |
| A WASM library | The `WebAssembly` API or an ES module import from JS/TS | Exposes the module's exports. |
To compile Java or Kotlin to WebAssembly, see [WebImage](https://elide.help/docs/toolchain/jvm/webimage); its output needs its JavaScript
loader, not `elide run`. Target guides: [Browser WASM](https://elide.help/docs/toolchain/web/wasm) and [Edge WASM](https://elide.help/docs/toolchain/edge/wasm).
## Run a WASM file
```bash
elide run app.wasm
elide app.wasm
elide run app.wasm -- first second # program arguments
elide run --timeout=5s app.wasm # exit 124 after 5 seconds
```
Elide calls the exported `_start`, or `_main` if `_start` is absent. Load a module with neither from JavaScript.
| Behavior | Value |
| --- | --- |
| Argument zero | The module's absolute path. |
| Exit status | Set by WASI `proc_exit`, not by a function's return value. |
| Traps, malformed binaries | Nonzero exit. |
| `--timeout` | Covers instantiation and execution; exits `124`. |
### Project entrypoints
Set the module as the entrypoint in `elide.pkl`, then run `elide run`:
```pkl
amends "elide:project.pkl"
name = "wasm-app"
entrypoint { "app.wasm" }
```
See [Project setup](https://elide.help/docs/projects).
## WASI
Commands get WASI Preview 1 imports under `wasi_snapshot_preview1`: standard streams, arguments, exit status, and
filesystem operations. Libraries loaded from JavaScript do not get WASI.
### Directory access
WASI commands see no host directories until you map one:
```bash
elide -Xpolyglot.wasm.WasiMapDirs=work::./data run app.wasm
```
This maps `./data` to the guest directory `work`. Separate mappings with commas: `work::./data,output::./results`.
The sandbox still applies. WASI file opens need read and write permission, even for reads:
```bash
elide -Xpolyglot.wasm.WasiMapDirs=work::./data run \
--sandbox --allow-read=./data --allow-write=./data app.wasm
```
See [Sandbox and Limits](https://elide.help/docs/sandbox).
## JavaScript and TypeScript interop
The global `WebAssembly` API needs no flag:
```javascript
import { readFile } from "node:fs/promises";
const bytes = await readFile(new URL("./math.wasm", import.meta.url));
const { instance } = await WebAssembly.instantiate(bytes, {});
console.log(instance.exports.add(20, 22));
```
Modules loaded from JavaScript do not run `_start` or `_main`. The second argument supplies the module's imports:
```javascript
const imports = { env: { log: (value) => console.log(value) } };
const { instance } = await WebAssembly.instantiate(bytes, imports);
```
The API includes `validate`, `compile`, `Module`, `Instance`, `Memory`, `Table`, `Global`, and import and export
inspection. A compiled `Module` can be instantiated more than once. File reads follow the usual permissions.
### ES module imports
```javascript
import { add } from "./math.wasm";
console.log(add(20, 22));
```
```javascript
const math = await import("./math.wasm");
console.log(math.add(20, 22));
```
Specifiers can be paths, `file:` URLs, or package exports that resolve to `.wasm`. A source-phase import returns
the compiled module to instantiate yourself:
```javascript
import source mathModule from "./math.wasm";
const math = await WebAssembly.instantiate(mathModule, {});
console.log(math.exports.add(20, 22));
```
## Supported WebAssembly proposals
On by default, for commands and JS/TS interop:
- Mutable globals and sign-extension operators
- Non-trapping float-to-integer conversions
- Multi-value function and block results
- Bulk memory operations and reference types
- Multiple memories
- Extended constant expressions
- Exception handling
- Typed function references
- Garbage-collected types (WasmGC)
- Tail calls
- Fixed-width SIMD (`v128`) and relaxed SIMD, except with Python installed
Off by default:
| Proposal | Option | Notes |
| --- | --- | --- |
| Memory64 | `wasm.Memory64` | Also requires `wasm.UseUnsafeMemory`. |
| Threads and atomics | `wasm.Threads` | No WASI thread-spawning host API is supplied. |
| Wide integer arithmetic | `wasm.WideArithmetic` | Separate from ordinary `i64` arithmetic. |
| Legacy exception handling | `wasm.LegacyExceptions` | The newer exception-handling proposal is on by default. |
Enable one with `-Xpolyglot.