Getting Started with Joule

This guide walks you through installing the Joule compiler and writing your first program.

Current version: v1.2.0

Install

PlatformCommand
macOS / Linuxbrew install openIE-dev/joule/joule
Windowswinget install OpenIE.Joule
Ubuntu / Debiansudo apt install joule (after adding the repo)
Arch Linuxyay -S joule-bin
Nixnix run github:openIE-dev/joule-lang
Snapsudo snap install joule --classic
Any (curl)curl -fsSL https://joule-lang.org/install.sh | sh

macOS

Homebrew (recommended):

brew install openIE-dev/joule/joule

Or download joule-macos-arm64.pkg (Apple Silicon) or joule-macos-x86_64.pkg (Intel) from the releases page:

sudo installer -pkg joule-macos-arm64.pkg -target /

Windows

Winget (recommended, built into Windows 11):

winget install OpenIE.Joule

Scoop:

scoop bucket add joule https://github.com/openIE-dev/scoop-joule
scoop install joule

Chocolatey:

choco install joule

Or download joule-windows-x86_64.msi or joule-windows-arm64.msi from the releases page. The MSI installer adds joulec to your PATH automatically.

APT (Ubuntu/Debian)

curl -fsSL https://openie-dev.github.io/joule-lang/KEY.gpg | sudo gpg --dearmor -o /usr/share/keyrings/joule.gpg
echo "deb [signed-by=/usr/share/keyrings/joule.gpg] https://openie-dev.github.io/joule-lang stable main" | sudo tee /etc/apt/sources.list.d/joule.list
sudo apt update && sudo apt install joule

Arch Linux (AUR)

yay -S joule-bin

Or with any AUR helper: paru -S joule-bin, trizen -S joule-bin.

Nix

# Run without installing
nix run github:openIE-dev/joule-lang

# Install into profile
nix profile install github:openIE-dev/joule-lang

Snap

sudo snap install joule --classic

Install Script

Universal one-line installer for macOS and Linux:

curl -fsSL https://joule-lang.org/install.sh | sh

From Source

git clone https://github.com/openIE-dev/joule-lang.git
cd joule-lang && cargo build --release

From C Source (Zero Dependencies)

Download joule-c-src-*.tar.gz from the releases page:

tar xzf joule-c-src-*.tar.gz && cd joule-c-src-*
make    # or: cc -O2 -o joulec output.c -lm

Verify

joulec --version
# joulec 1.2.0

Write Your First Program

Create a file called hello.joule:

pub fn main() {
    let message = "Hello from Joule!";
    println!("{}", message);
}

Compile and Run

joulec hello.joule -o hello
./hello

Output:

Hello from Joule!

Try JIT Mode

For interactive development, skip the compile step entirely:

joulec --jit hello.joule

This JIT-compiles and runs your program in memory using the Cranelift backend. No intermediate files are produced.

For an even faster workflow, use watch mode. It monitors your source file and re-runs automatically when you save:

joulec --watch hello.joule

JIT mode requires the jit feature flag. See JIT Compilation for details.

Add an Energy Budget

Joule's defining feature is compile-time energy budget verification. Annotate your function with an energy allowance:

#[energy_budget(max_joules = 0.0001)]
pub fn main() {
    let x = 42;
    let y = 58;
    let result = x + y;
    println!("{}", result);
}

Compile with energy checking:

joulec hello.joule -o hello --energy-check

The compiler estimates the energy cost of your function at compile time. If it exceeds the declared budget, compilation fails with a diagnostic showing the estimated vs. allowed energy.

Measure Energy in Existing Code

Already have Python or JavaScript code? Joule can measure its energy consumption without rewriting it:

# Measure energy in a Python script
joulec --lift-run python script.py

# Measure energy in a JavaScript file
joulec --lift-run js app.js

# Apply energy optimization before running
joulec --energy-optimize --lift-run python script.py

The --lift-run flag lifts foreign code into Joule's intermediate representation, applies energy analysis, and executes it. See Polyglot Energy Analysis for details.

Batteries Included

Joule ships with 110+ standard library modules. No package manager needed for common tasks:

use std::math;
use std::collections::HashMap;
use std::io::File;
use std::net::TcpStream;
use std::crypto::sha256;

See the Standard Library Reference for the complete list.

Feedback

Joule is developed and maintained by Open Interface Engineering, Inc. We welcome bug reports, feature requests, and questions via joule-lang.org or GitHub Issues.

Next Steps