Installation

To use jbang Java 8 is the minimum required version, however Java 17 or higher is recommended. To use jbang Java 8 is the minimum required version, however Java 17 or higher is recommended.

Note: jbang will download and install java from Eclipse Temurin if no java is available. Note: jbang will download and install java from Eclipse Temurin if no java is available.

There are multiple ways to install jbang. See below for all available options.

Once you have jbang installed, it is recommended you run jbang app setup. This script will make the following changes to your system:

  1. Modify PATH environment variable to include jbang app scripts

  2. For supported shells, add j! as an alias for jbang. Try running j! version to verify.

By default jbang uses ~/.jbang for configurations and build cache. This can be changed using the environment variable JBANG_DIR.

Installation Methods

Universal (All Platforms)

Using JBang (curl/bash)

Linux/OSX/Windows/AIX Bash:

curl -Ls https://sh.jbang.dev | bash -s - app setup

Windows Powershell:

iex "& { $(iwr -useb https://ps.jbang.dev) } app setup"

Zero Install (curl/bash and Powershell)

Linux/OSX/Windows/AIX Bash:

curl -Ls https://sh.jbang.dev | bash -s - <arguments>

For example curl -Ls https://sh.jbang.dev | bash -s - properties@jbangdev

Windows Powershell:

iex "& { $(iwr -useb https://ps.jbang.dev) } <arguments>"

For example iex "& { $(iwr -useb https://ps.jbang.dev) } properties@jbangdev"

Manual install

Unzip the latest binary release, add the jbang-<version>/bin folder to your $PATH and you are set.

Wrapper install

If you would like to have jbang available in a local directory and committed into a source code repository (akin to Maven and Gradle wrappers) you can use the jbang wrapper command.

If you have jbang already installed you call jbang wrapper install in a folder to install a local jbang that will run out of that directory using ./jbang.

The ./.jbang directory which jbang wrapper install creates is just a cache which you typically would not commit to a source code repository, so you can e.g. echo .jbang/ >>.gitignore.

Linux & macOS

SDKMan

Although if you want to have easy updates or install multiple JBang versions we recommend sdkman to install both java and jbang on Linux and OSX.

curl -s "https://get.sdkman.io" | bash (1)
source ~/.bash_profile (2)

sdk install java (3)

Once Java is installed and ready, you install jbang with

sdk install jbang

To test your installation run:

jbang --help

This should print out usage information.

To update run:

sdk upgrade jbang

asdf

You can install JBang using the asdf version manager:

asdf plugin-add jbang
asdf install jbang latest

Homebrew (macOS)

On OSX you can install 'java' and jbang with Homebrew using custom taps.

To install Java 17:

brew install temurin@17 --cask

Once Java is installed you can use brew with jbangdev/tap to get jbang:

brew install jbangdev/tap/jbang

To upgrade to latest version:

brew upgrade jbangdev/tap/jbang

(Experimental) Linux packages

These builds are not fully automated yet thus might be slightly behind.

You can install rpm packages from Fedora Copr by doing the following:

dnf copr enable @jbangdev/jbang
dnf install jbang

The COPR currently includes builds from various versions of CentOS, Fedora, Mageia and OpenSuse.

Windows

Chocolatey

On Windows you can install both java and jbang with Chocolatey.

From a command prompt with enough rights to install with choco:

choco install jdk11

Once Java in installed run:

choco install jbang

To upgrade to latest version:

choco upgrade jbang

The latest package will be published to jbang choco package page, it might be a bit delayed as the review is still manual. In case the default version is not the latest you can see the version list and install specific version using:

choco install jbang --version=<version number>

Scoop

On Windows you can also install jbang with Scoop.

scoop bucket add jbangdev https://github.com/jbangdev/scoop-bucket
scoop install jbang

To upgrade to latest version:

scoop update jbang

Homebrew

On OSX you can install 'java' and jbang with Homebrew using custom taps.

To install Java 11:

brew tap AdoptOpenJDK/openjdk
brew install adoptopenjdk11 --cask

Once Java is installed you can use brew with jbangdev/tap to get jbang:

brew install jbangdev/tap/jbang

To upgrade to latest version:

brew upgrade jbangdev/tap/jbang

(Experimental) Linux packages

These builds are not fully automated yet thus might be slightly behind.

You can install rpm packages from Fedora Copr by doing the following:

dnf copr enable @jbangdev/jbang
dnf install jbang

The COPR currently includes builds from various versions of CentOS, Fedora, Mageia and OpenSuse.

Docker / GitHub Action

You can run jbang via Docker:

docker run -v `pwd`:/ws --workdir=/ws -ti jbangdev/jbang-action helloworld.java

or if you prefer using Quay.io:

docker run -v `pwd`:/ws --workdir=/ws -ti quay.io/jbangdev/jbang-action helloworld.java

The same container images can be used with GitHub Actions, see jbang-action for details.

Remember to remove -ti from the commands above when using on a GitHub Actions flow.

GitHub Actions

You can use JBang in your GitHub Actions workflows:

- name: Setup JBang
  uses: jbangdev/setup-jbang@main

- name: Run script
  run: |
    jbang properties@jbangdev

See https://github.com/marketplace/actions/setup-jbang for more details.

Build Tools

Maven Plugin

The JBang Maven plugin allows JBang scripts to be executed during a Maven build.

Example in your pom.xml:

<plugin>
<groupId>dev.jbang</groupId>
<artifactId>jbang-maven-plugin</artifactId>
<version>0.0.8</version>
<executions>
  <execution>
    <id>run</id>
    <phase>process-resources</phase>
    <goals>
      <goal>run</goal>
    </goals>
    <configuration>
        <script>hello.java</script>
    </configuration>
  </execution>
</executions>
</plugin>

The plugin documentation and more examples are available here: https://github.com/jbangdev/jbang-maven-plugin

Gradle Plugin

The JBang Gradle plugin allows JBang scripts to be executed during a Gradle build.

In your build.gradle file, add:

plugins {
    id 'dev.jbang' version '0.2.0'
}

That will allow you to execute JBang scripts with:

$ gradle jbang --jbang-script hello.jsh --jbang-args="Hello world"

The plugin documentation and more examples are available here: https://github.com/jbangdev/jbang-gradle-plugin

Programming Language Integrations

JavaScript/Node.js (npx/npm)

You can use JBang via Node.js using npx or by installing the npm package:

npx @jbangdev/jbang app setup

Or add to your package.json:

{
  "devDependencies": {
    "@jbangdev/jbang": "^0.1.4"
  }
}

And use in your scripts:

// test.js:
#! /usr/bin/env node
const jbang = require('@jbangdev/jbang');
jbang.exec('properties@jbangdev');

Python (pipx/uvx/pip)

You can use JBang from Python environments:

pipx jbang app setup
uvx jbang app setup

Or in a Jupyter notebook:

!pip install jbang
import jbang
jbang.exec('properties@jbangdev')

Download Retries

When JBang downloads a JDK or JBang itself during first-time setup, it will automatically retry on failure. By default, downloads are retried up to 5 times. This is especially useful in CI environments where transient network errors can cause spurious failures.

You can control the number of retries by setting the JBANG_DOWNLOAD_RETRY environment variable:

# Increase retries for flaky CI networks
export JBANG_DOWNLOAD_RETRY=10

# Disable retries
export JBANG_DOWNLOAD_RETRY=0

This setting works consistently across all platforms:

  • Linux/macOS (bash): Applies to both curl (--retry) and wget (--tries)

  • Windows (PowerShell): Applies to Invoke-WebRequest via a retry loop

  • Windows (CMD): Delegates to PowerShell, so the same retry logic applies

You can also control the delay between retries with JBANG_DOWNLOAD_RETRY_DELAY. The default is 0, which uses progressive backoff — the delay increases between each retry attempt (e.g., 1s, 2s, 4s, 8s, …​). This avoids overwhelming a server that is already struggling and is the recommended setting for CI. Set to a positive number of seconds for a fixed delay between every retry instead.

Custom Download URL

By default JBang downloads itself from GitHub. You can override the download URL by setting JBANG_DOWNLOAD_URL, for example to use a corporate mirror:

export JBANG_DOWNLOAD_URL=https://internal-mirror.example.com/jbang/jbang.tar

Downloading a specific version or the early-access build

Set JBANG_DOWNLOAD_VERSION to pick a specific release. Numeric values are resolved to the matching vX.Y.Z GitHub release; any other value is used as a release tag name as-is. This means you can opt-in to the perpetual early-access build with a simple:

export JBANG_DOWNLOAD_VERSION=early-access

which resolves to https://github.com/jbangdev/jbang/releases/download/early-access/ . Equivalent forms:

export JBANG_DOWNLOAD_VERSION=0.120.0     # -> .../download/v0.120.0/jbang.tar
export JBANG_DOWNLOAD_VERSION=early-access # -> .../download/early-access/jbang.tar

Version Check

jbang will check once a day if a new version is available. If a new version is available a message will be printed with information on how to install.

The check happens in the background and will only be done every 24 hours on the same installation.

The version check is done via a HTTP request to fetch a version.txt from https://jbang.dev. The request includes a user-agent that contains the current jbang, java and operating system version with no person identifiable information which we use purely to aggregate statistics to know update/usage frequency. Those statistics are published at https://jbang.dev/usage

jbang will not do its automatic check for version when you run in --offline mode nor if you set JBANG_NO_VERSION_CHECK environment variable.

Example:

jbang test.java ## if more than 24hrs last check version will be checked
export JBANG_NO_VERSION_CHECK
jbang test.java ## no version check made as JBANG_NO_VERSION_CHECK is set

Startup Script Environment Variables

The JBang startup scripts (jbang, jbang.cmd, jbang.ps1) use the following environment variables. These are read by the scripts themselves before Java or JBang’s Java code is invoked.

Variable Default Description

JBANG_DIR

~/.jbang

Root directory for JBang configuration, installed apps, and (unless overridden) the cache.

JBANG_CACHE_DIR

$JBANG_DIR/cache

Directory for cached JDKs, compiled scripts, and downloaded content.

JBANG_DEFAULT_JAVA_VERSION

17

Java version to install when no JDK is found on the system.

JBANG_JDK_VENDOR

temurin (for 8, 11, 17+)
aoj (others)

JDK distribution to download. Passed as the distro parameter to the Foojay Disco API.

JBANG_DOWNLOAD_RETRY

5

Number of retry attempts for downloading JDK or JBang archives. Set to 0 to disable retries.

JBANG_DOWNLOAD_RETRY_DELAY

0

Delay in seconds between download retry attempts. 0 (default) uses progressive backoff (1s, 2s, 4s, 8s, …​). A positive value uses a fixed delay between every retry.

JBANG_DOWNLOAD_URL

(GitHub releases)

Override the URL used to download JBang itself. Useful for corporate mirrors or air-gapped environments.

JBANG_DOWNLOAD_VERSION

(latest)

Specific JBang version to download. Numeric values (e.g., 0.120.0) are resolved to the matching vX.Y.Z GitHub release; any non-numeric value (e.g., early-access) is used as a release tag name as-is. When unset, the latest release is used.

JBANG_JAVA_OPTIONS

(empty)

Additional JVM options passed when running JBang’s Java code (e.g., -Xmx512m).

JBANG_USE_NATIVE

false

When set to true, use the native binary (jbang.bin / jbang.bin.exe) instead of the JAR.

JBANG_NO_VERSION_CHECK

(unset)

When set (to any value), disables the automatic check for new JBang versions.

The following variables are set by the scripts for use by JBang’s Java code and are not intended to be set by users:

Variable Description

JBANG_RUNTIME_SHELL

The shell running the script (bash, cmd, or powershell).

JBANG_STDIN_NOTTY

true if stdin is not a terminal, false otherwise.

JBANG_LAUNCH_CMD

Path to the script that was invoked.