JBang: Run Java Source Files and JARs

JBang's single-file execution model

JBang targets Java programs that can be treated as self-contained commands. The README describes three starting points: a local `.java` file, a Maven GAV coordinate such as `com.github.lalyos:jfiglet:0.0.9`, or a URL. This makes JBang useful for teachers who want students to run a small example immediately, students experimenting with libraries, and developers who need a one-off utility without first creating a Maven or Gradle project.

The core workflow is to point JBang at an artifact and let it perform the preparation normally associated with a Java build. According to the README, that preparation includes downloading a JDK when needed, resolving dependencies, compiling the source, caching the result, and running the program. The important design choice is that dependency metadata can live beside the source instead of in a separate build file.

For a single-file program, JBang reads `//DEPS` comments and pulls the named packages from Maven Central or a configured repository. The directive syntax is shown in the README as:

//DEPS info.picocli:picocli:4.6.3

That keeps the dependency declaration close to the code that needs it. JBang also recognizes `.jsh` files for JShell, `.kt` for Kotlin, `.groovy`, and `.md` files containing embedded Java. The README also says that any JAR can be run directly. The practical result is a command-line entry point that works for several Java-related formats, rather than a project generator tied to one build system.

JBang is therefore most convincing when the program is small enough for source-level instructions to remain understandable. A file can also contain a shebang-like JBang line, a Java version requirement, dependencies, and runtime options. That makes a script shareable, but the metadata is still embedded in a text file rather than maintained in a conventional dependency model.

How JBang prepares and runs a program

The documented pipeline has several distinct responsibilities. First, JBang identifies the requested target. For a local source file, it reads the file and its JBang directives. For a GAV coordinate, it identifies a Maven artifact. For a URL, the README lists remote scripts as another supported source.

Next, JBang can download a JDK if the local environment does not provide a suitable one. Source files can declare a required Java level with a `//JAVA` directive. The examples use `//JAVA 25+`, so a file can communicate its execution expectation without a separate configuration file. The README does not describe the exact JDK selection algorithm or all supported Java versions, so those details should be checked in the installation and usage documentation before relying on a specific runtime.

Dependency resolution then places the requested packages on the classpath. The README identifies Maven Central and custom repositories as supported sources. Compilation and caching are handled as part of the command execution. These details are important because they distinguish JBang from a simple wrapper around `java`: it is responsible for both the build preparation and the launch process.

The command-line surface extends beyond execution. The README lists commands for editing a source file in an IDE, opening a debug port, producing a native binary through GraalVM, installing an application as a system command, exporting to a Maven project, adding an alias, and running a script from a URL. These commands show that JBang treats a source program as a small application that can move between direct execution and more conventional project packaging.

Installing JBang and running the first CLI

The shortest installation path in the README uses a shell command that runs the installer and sets up the JBang application. The command then creates a CLI example and executes it:

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

The first command obtains JBang through the documented setup command. The second creates `hello.java` from the `cli` template. The third runs the generated file with `Max!` as an argument. The expected result is a greeting, although the README does not reproduce the generated file's output separately.

Other installation routes use existing package managers. The documented commands are:

sdk install jbang

brew install jbangdev/tap/jbang

choco install jbang

scoop install jbang

These options correspond to SDKMan, Homebrew, Chocolatey, and Scoop. The README points to the JBang installation documentation for the complete list of options, so the package-manager examples should be treated as starting points rather than as a complete platform matrix.

After setup, a source file can be run directly. The README's minimal Java example uses a shebang-style invocation, a Java version directive, and a `main` method:

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

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

The same file is suitable for a quick real use because it accepts an optional argument and prints either that argument or `World`. The README does not document rollback or uninstall steps, so those operations should be checked in the linked installation documentation rather than assumed.

Dependencies, versions, and runtime options

JBang's directives reduce the number of files needed for a small program, but they also put build decisions in comments that a conventional project might represent elsewhere. The CLI example declares both a dependency and a Java baseline:

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

The dependency is picocli, and the example uses it to parse a positional greeting parameter. The Java directive requests Java 25 or later. This is a clear tradeoff: the source is easy to copy and run, while version changes are visible in the script itself.

Runtime options use a separate directive. The Javalin example in the README includes logging configuration:

//DEPS io.javalin:javalin:7.1.0
//DEPS org.slf4j:slf4j-simple:2.0.17
//RUNTIME_OPTIONS -Dorg.slf4j.simpleLogger.defaultLogLevel=info
//JAVA 25+

This makes the example self-describing enough to configure logging without a separate launcher file. It also illustrates a limitation. The directives are convenient for a script, but they do not provide the same project-wide dependency management, lockfile behavior, or build-stage separation that teams may expect from Maven or Gradle. The README does not claim that JBang produces such a lockfile.

For code that already has a substantial dependency graph, exporting is the documented escape hatch. The command below exports `myapp.java` as a Maven project:

jbang export maven myapp.java

That changes the workflow after the initial script phase. JBang can remain the direct execution tool while Maven takes over the conventional project structure, provided the exported project is inspected before it is used for a release.

When JBang is the wrong tool

The main limitation is organizational rather than a missing runtime feature. JBang is designed around source-only programs and command-line execution. A team maintaining a multi-module application, reusable library, or release pipeline may need a build file at the repository root, shared configuration across modules, and an artifact publication process. The README presents Maven export, not a documented Gradle export or a complete alternative build lifecycle.

There is also a supply-chain decision. `//DEPS` lines cause JBang to resolve packages from Maven Central or the user's repositories. That is convenient for a classroom example, but production teams need to decide which coordinates are acceptable, whether versions are pinned, and how dependency changes are reviewed. The README does not document a dependency verification or lockfile mechanism, so it should not be inferred from the caching behavior.

The App Store is another boundary to consider. The README says it contains community-contributed scripts and tools that can be run directly. That is useful for discovery, but the existence of an entry does not establish who reviewed its dependencies or how it should be deployed. For a first experiment, this is acceptable. For an internal production command, the repository and artifact coordinates should be inspected first.

A related constraint is Java-version availability. The examples request Java 25 or later. The README says JBang can download a JDK when needed, but it does not specify every supported distribution or all environment restrictions. A machine with restricted outbound access, a locked-down artifact repository, or a requirement to use a centrally managed JDK should verify those cases separately.

JBang compared with Maven and Gradle

The practical alternative is a conventional Maven or Gradle project, not another script runner. Maven and Gradle represent dependencies, plugins, compilation tasks, and packaging as project configuration. JBang instead keeps the dependency list beside a single source file and performs preparation when the script is run. That difference makes JBang quicker for a small program and less explicit for a larger codebase.

Maven is especially relevant because JBang provides `jbang export maven myapp.java`. That command gives a direct migration path when a script has grown beyond the point where an embedded `//DEPS` list is sufficient. A Gradle-based team would need to use Gradle's own project conversion or build configuration, since the README does not document a Gradle export command. JBang should not be described as a replacement for either build system. It is a front door to Java execution, with an export path for one ecosystem.

Compared with manually invoking `java`, JBang adds JDK acquisition, dependency resolution, compilation, and caching. Compared with Maven or Gradle, it reduces initial setup for one file. Those are meaningful differences, and the choice depends on whether the immediate goal is running a program or maintaining a repeatable multi-module build.

JBang releases, maintenance, and MIT terms

The repository is not archived, and its last push was on 2026-10-09. The listed releases include `early-access` on 2026-10-07, `v0.142.0` on 2026-09-22, and `v0.141.0` on 2026-07-14. This indicates recent project activity, but the release labels also show that users should distinguish a stable version from an early-access build. The README does not define the compatibility policy for those labels, so production users should read the release notes before selecting a version.

The project is released under the MIT License and is identified as a Commonhaus Foundation project. MIT licensing generally means that the software is made available under permissive terms, but the actual obligations come from the repository's `LICENSE` file and the licenses of dependencies. JBang's MIT license does not remove the need to review the licenses of packages resolved through `//DEPS`, the JDK, GraalVM, or any application it runs. The README does not provide legal advice or a dependency-license report.

Maintenance cost is low for a small script that remains self-contained. It rises when a project accumulates dependencies, Java-version requirements, runtime options, and deployment expectations. The documented release and export commands provide concrete options for controlling that transition: pin the JBang version used by automation, inspect `export maven` output, and verify the resulting project before publishing.

Editorial conclusion

JBang suits students, educators, Java educators, and developers who need a disposable command-line program or a quick way to run a JAR. It is a poor fit for teams that require a conventional build pipeline, checked-in dependency declarations, or deployment artifacts from the start. Before adopting it, verify the dependency directives, Java version requirements, export target, and command installation behavior against the documentation for the specific program.

Frequently asked questions

Official sources

1. jbangdev/jbang on GitHub
2. License: MIT
3. Project website
4. README
5. Releases