BeanShell: a small Java interpreter you can drop into a running JVM

Loose types and commands on top of standard Java syntax

BeanShell is described as a small, free, embeddable Java source interpreter written in Java, with object scripting language features. It executes standard Java syntax dynamically and extends it with scripting conveniences such as loose types, commands and method closures, in the vein of Perl and JavaScript.

That combination is the whole pitch. You get the Java grammar you already know, including access to the platform classes in the same VM, without the ceremony of compilation, declaration and type signatures. A script can be a one liner that manipulates objects, or a configuration file that a rules engine evaluates.

The intended users are split across two modes. One is a developer experimenting in the interpreter or teaching Java to someone who already knows a scripting language. The other is a Java application team that wants to expose extensibility: rapid prototyping, user scripting extension, rules engines, configuration, testing, dynamic deployment and embedded systems are the applications the introduction lists. The scale is deliberate. This is a small interpreter meant to sit inside something else, not a platform that replaces one.

Scripts run inside the host VM and hand back live references

The architectural decision that matters is that BeanShell is written in Java and runs in the same VM as the application that calls it. Because of that, the documentation states you can freely pass references to live objects into scripts and return them as results.

So the data flow is direct object flow. A host Java class calls the interpreter, hands it an object, the script mutates or reads it, and returns something that is still the same object rather than a copy. There is no serialisation boundary and no separate process. For a rules engine evaluating predicates against business objects, that removes an entire layer of mapping code that a JVM-hosted scripting engine would otherwise force on you.

The repository layout reflects a library rather than an application: src/, pom.xml, build.xml, maven-build.xml, maven-build.properties, a scripts/ folder with the bsh and bsh.bat helpers, and a bsh-bsf-engine/ directory. The project is packaged for Maven, with a pom.xml as the primary build and the older Ant files kept alongside it.

Building from main and pulling the interpreter from Maven Central

The development branch is main, and the README says that version is the one to use. Building requires JDK 8 or newer and Maven:

$ mvn install

The resulting JAR targets Java 8 and the README states it runs on Java 8, Java 11, Java 17, Java 21 and Java 25. For a clean build the Build section gives:

$ mvn clean install

Published artifacts live on Maven Central under the io.github.beanshell groupId. The legacy 2.1.1 release is available now:

    <dependencies>
       <dependency>
         <groupId>io.github.beanshell</groupId>
         <artifactId>bsh</artifactId>
         <version>2.1.1</version>
       </dependency>
    </dependencies>

and the release candidate is available under the same coordinates:

    <dependencies>
       <dependency>
         <groupId>io.github.beanshell</groupId>
         <artifactId>bsh</artifactId>
         <version>3.0.0RC1</version>
       </dependency>
    </dependencies>

Note the version string. A dependency on a release candidate is a deliberate choice, not a typo, and it is the version most of the outstanding fixes have landed on.

Running the desktop UI and the interactive interpreter

BeanShell can be used without any host application at all. The releases page ships a standalone binary, bsh.jar, and the README shows two ways to start it.

Double-clicking the JAR opens the BeanShell User Interface, and the same effect is available from a terminal:

$ java -jar bsh-3.0.0RC1.jar

For an interactive shell rather than the desktop interface, the interpreter class is invoked directly:

$ java -cp bsh-3.0.0RC1.jar bsh.Interpreter

On platforms where the double-click route is inconvenient, the repository ships helper scripts named bsh and bsh.bat under the scripts folder, which wrap the same startup. The downloadable artifacts are listed as bsh-3.0.0RC1.jar for the release candidate and bsh-2.1.1.jar for the legacy line, and source zips are published alongside them.

One practical note from the README: BeanShell 3.0 needs Java 8 or later. If you plan to embed the interpreter rather than run it standalone, the JAR's Java 8 baseline is the floor you are designing against.

The SecurityGuard file is where the risk lives

Executing Java source at run time is a capability with consequences. The repository includes a dedicated SecurityGuard.md that the README points at for Java embedding examples and application-defined script policies. If you plan to let users supply scripts, that file is the part to read before anything else.

The failure mode here is specific. A BeanShell script has the reach of the host process, so a script that reaches outside the intended surface is not a syntax problem, it is a boundary problem. The existence of a policy guide tells you the project treats this as a first class concern rather than an afterthought, and it is the natural place to define what a script is permitted to touch.

There is a matching caveat on the side of convenience. Because scripts share the VM, there is no process isolation by default. A host application that accepts scripts from an untrusted source needs the kind of policy described in SecurityGuard.md rather than the default behaviour, and that work is on the adopter.

Legacy 2.1.1 versus a 3.0 release candidate still missing documentation

The repository is not archived and the last push was on 2026-10-21. The release record shows 3.0.0RC1 on 2026-10-12, 3.0.0b1 on 2026-09-23, and then a long gap back to 2.1.1 on 2022-12-02. The gap is the story: the 2.x line sat quiet for years while 3.0 was assembled.

The state of 3.0 is candid in a way few project READMEs are. The notice says support for legacy releases reached end of life and that only issues and pull requests against main will be accepted. Most outstanding issues were imported from SourceForge, where they were reported many years ago and now sit orphaned without owners. The README states the majority has already been resolved on main and asks for help processing the rest to verify whether they are still valid, reproducible, or already resolved.

Some things are explicitly out of scope for 3.0 and scheduled for the next release: StrictJava compliance, unit tests, and outstanding issues, plus updated documentation. That last item matters most. The documentation link points at the older site at beanshell.org, and the wiki discussions are described as doubling as future documentation. In other words, the written reference for 3.0 is thin on purpose, and MIGRATION.md and CHANGES.md are the practical sources for compatibility and build notices.

Apache 2.0 terms, with a NOTICE file to keep

Starting with version 2.0b5, BeanShell is licensed under the Apache License, version 2.0. The repository carries both LICENSE and NOTICE at the top level, and the README specifically points at the NOTICE file for required attributions.

For an embeddable library that ships inside a product, that NOTICE requirement is the practical item to track. Redistributing BeanShell inside a larger application means carrying the attribution forward, and the Apache 2.0 licence also carries the usual conditions around stating changes and preserving notices. None of that needs legal advice, it simply needs a place in your release checklist rather than being discovered at audit time.

The licensing point is worth one more sentence because BeanShell is often pulled in indirectly, through a build plugin, a test harness or a dependency of another library. A transitive BeanShell is still a redistributed BeanShell. Tracking it from the start is cheaper than discovering the NOTICE obligation from a dependency report.

Editorial conclusion

BeanShell suits Java teams that want a scripting layer for configuration, rules or user extension inside a JVM that is already running, and that can accept a candidate release in a non critical service. It is a poor fit for code that must be reproducible today, since the current 3.0.0RC1 is a candidate with legacy support at end of life, and a poor fit for environments where executing user supplied Java source would be unsafe. Before adopting, check the MIGRATION.md compatibility examples against your own source, read SecurityGuard.md to decide what a script is allowed to do, and confirm that your JDK is one of the versions the JAR claims to run on.

Frequently asked questions

Official sources

1. beanshell/beanshell on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases