readme.adoc

July 4, 2026 ยท View on GitHub

= JBang - Unleash the Power of Java :idprefix: :idseparator: -

image:images/jbang_logo.svg[JBang Logo, 400]

Run any JAR or Java source file directly. JBang handles JDK downloads, dependency resolution, compilation, and caching so you can use the full Java ecosystem without the ceremony.

image:https://img.shields.io/github/release/jbangdev/jbang.svg[Release,link=https://github.com/jbangdev/jbang/releases] image:https://img.shields.io/github/downloads/jbangdev/jbang/total.svg[Downloads,link=https://hanadigital.github.io/grev/?user=jbangdev&repo=jbang] image:https://github.com/jbangdev/jbang/workflows/ci-build/badge.svg[Build Status,link=https://github.com/jbangdev/jbang/actions] image:https://api.scorecard.dev/projects/github.com/jbangdev/jbang/badge[OpenSSF Scorecard,link=https://scorecard.dev/viewer/?uri=github.com/jbangdev/jbang] image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[Chat,link=https://jbangdev.zulipchat.com/]

== Get started

[source, bash]

curl -Ls https://sh.jbang.dev | bash -s - app setup jbang init --template=cli hello.java jbang hello.java Max!

Or install via https://sdkman.io[SDKMan] (sdk install jbang), https://brew.sh[Homebrew] (brew install jbangdev/tap/jbang), https://community.chocolatey.org/packages/jbang[Chocolatey] (choco install jbang), or https://scoop.sh[Scoop] (scoop install jbang).

See the https://jbang.dev/documentation/jbang/latest/installation.html[installation docs] for all options.

image:https://asciinema.org/a/4AiobRxUwPUPztCtrDYcmoKjs.svg[link=https://asciinema.org/a/4AiobRxUwPUPztCtrDYcmoKjs?autoplay=true&theme=solarized-dark]

== What JBang does

At its simplest, JBang runs JARs and Java source files directly from the command line. Point it at a GAV coordinate, a URL, or a local .java file and it takes care of the rest: downloading a JDK if needed, resolving dependencies, compiling, caching, and running.

For single-file programs you declare dependencies with //DEPS comments instead of a build file. That is enough to pull anything from Maven Central (or your own repos) and have it on the classpath.

JBang also works with .jsh (JShell), .kt (Kotlin), .groovy, and .md (Markdown with embedded Java).

== Examples

Run any JAR from Maven Central by its GAV coordinate:

[source, bash]

jbang com.github.lalyos:jfiglet:0.0.9 "Hello JBang!"

A plain Java file with a naked main (Java 25+):

[source, java]

///usr/bin/env jbang "$0" "@";exit@" ; exit ? //JAVA 25+

void main(String[] args) { System.out.println("Hello " + (args.length > 0 ? args[0] : "World")); }

A CLI app with a dependency pulled from Maven Central:

[source, java]

///usr/bin/env jbang "$0" "@";exit@" ; exit ? //DEPS info.picocli:picocli:4.6.3 //JAVA 25+

import picocli.CommandLine; import picocli.CommandLine.Command; import picocli.CommandLine.Parameters;

@Command(name = "hello", mixinStandardHelpOptions = true) class hello implements Runnable { @Parameters(index = "0", description = "The greeting to print") private String greeting;

void main(String[] args) {
    new CommandLine(new hello()).execute(args);
}

public void run() {
    System.out.println("Hello " + greeting);
}

}

A web server in a single file:

[source, java]

///usr/bin/env jbang "$0" "@";exit@" ; exit ? //DEPS io.javalin:javalin:7.1.0 //DEPS org.slf4j:slf4j-simple:2.0.17 //JAVA 25+

import io.javalin.Javalin;

void main() { Javalin.create(config -> { config.useVirtualThreads = true; config.router.mount(router -> { router.get("/", ctx -> ctx.result("Hello from JBang!")); }); }).start(8000); }

== What else you can do

[source, bash]

jbang edit myapp.java # Open in IDE with full IntelliSense jbang --debug myapp.java # Run with debug port open for your IDE jbang --native myapp.java # Compile to native binary via GraalVM jbang app install myapp.java # Install as a system command jbang export maven myapp.java # Export to a Maven project jbang alias add myapp myapp.java # Create a short alias jbang https://gist.github.com/... # Run scripts from URLs

== App Store

JBang can run any Java application packaged as a JAR. The https://jbang.dev/appstore[App Store] has community-contributed scripts and tools you can run directly.

== Documentation

Full user documentation is at https://jbang.dev/documentation[jbang.dev/documentation].

There is also an AI-generated technical reference at https://deepwiki.com/jbangdev/jbang[deepwiki.com/jbangdev/jbang] built from the source code.

== Community

== Contributing

Contributions are welcome. See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for details.

== Thanks

JBang was inspired by https://github.com/holgerbrandl/kscript[kscript] by Holger Brandl.

JBang is a https://www.commonhaus.org[Commonhaus Foundation] project, released under the https://github.com/jbangdev/jbang/blob/main/LICENSE[MIT License].