For the complete documentation index, see llms.txt. This page is also available as Markdown.

Installation

Getting started with BoxLang is easy! Choose your path wisely!

BoxLang can be deployed on multiple runtimes, and each runtime can be set up differently. We recommend you leverage the "Running BoxLang" section for those specific runtimes. We recommend getting started by installing BoxLang at the global operating system level first. This is what this guide does!

You can choose to either install a single version of BoxLang (Quick Installer) or our BoxLang Version Manager (BVM), so you can manage multiple versions of BoxLang on your operating system.

Installing MatchBox

BoxLang also has a Rust runtime, MatchBox, for native binaries, the browser, WASI, AWS Lambda and ESP32. It installs separately with the MatchBox Version Manager, so no JVM is needed.

curl -fsSL https://raw.githubusercontent.com/ortus-boxlang/matchbox-quick-installer/main/install/install.sh | bash
mvm install latest && mvm use latest

Next Step: Learn with BoxLings

Requirements

BoxLang is a JVM language, so we need a JVM. You should be able to grab the Java 21 JRE for your OS and CPU arch here: Download Java 21 JRE. Alternatively, see the tabs below for instructions on automating it.

We recommend using Homebrew to get started on a Mac with the BoxLang by either installing our BoxLang Version Manager or the BoxLang Quick Installer. It will take care of all the requirements for you.

Leverage your system‘s package manager to install the needed requirements.

APT

Yum

Note that you may need to tell the system to use the correct JDK version. This can be done via update-alternatives --config java (sudo may be required).

XBPS (Voidlinux)

Note that you may need to tell the system to use the correct JDK version. This can be done via sudo xbps-alternatives -g jdk -s openjdk21

Arch Linux Variants

Note that you may need to tell the system to use the correct JDK version. This can be done via sudo archlinux-java set java-21-openjdk

Use the following PowerShell 7.x script to install the JRE 21. HOWEVER, MAKE SURE YOU RUN THIS AS AN ADMINISTRATOR.

Powershell 7.x:

Windows PowerShell (5.x):

  • Once this runs, the JRE will be installed in your C:\Program Files\Java\jre{version}

  • A JAVA_HOME will be created for you

Quick Installer

Once the requirements above are installed, get started quickly with BoxLang using our BoxLang Quick Installer for Mac, Linux, Unix, or Windows. This will allow you to execute the script in your favorite terminal application.

Please note that some OS will require you to run it as an administrator or with sudo capabilities.

You can see the full documentation for the quick installer in the link below:

BoxLang Quick Installer

Let's get started:

Just copy the following into your terminal to install by default for your user.

If you want a system-wide installation, then prefix it with sudo:

Please make sure you use the --help on our scripts to see everything you can do with them.

Make sure you have Homebrew installed:

Just copy the following into your terminal to install byin default for your user.

If you want a system-wide installation, then prefix it with sudo:

Please make sure you use the --help on our scripts to see everything you can do with them.

Just copy this into a Powershell Terminal. HOWEVER, MAKE SURE YOU RUN THIS AS AN ADMINISTRATOR.

Please make sure you use the --help on our scripts to see everything you can do with them.

The quick installer will install the latest stable BoxLang OS binary and the MiniServer in the above directories. It will also install the following scripts for you:

  • boxlang - Our BoxLang binary runner, learn more

  • boxlang-miniserver - Our BoxLang MiniServer binary runner, learn more

  • install-boxlang - The quick installer so you can reuse it to upgrade your installations or install the snapshot version of BoxLang. Run install-boxlang --help for more commands.

  • bx-module - The BoxLang module manager. Use bx-module install, remove, list, outdated, and update to manage modules from FORGEBOX. Run bx-module help for more commands.

  • install-bx-module - Deprecated legacy alias for bx-module. It prints a deprecation notice and forwards to bx-module.

Module Dependency Management

bx-module tracks installed modules in a box.json dependencies manifest. Global modules use:

For project-specific modules, use the --local flag. Local modules are managed in:

Installing or removing a module updates its dependency entry. bx-module list reads from this manifest and can generate one automatically when modules were installed before manifest tracking was added.

Use bx-module outdated to compare the installed versions with the latest versions available from ForgeBox:

Use bx-module update to update outdated modules, or pass module names to update only those. The command asks for confirmation before making changes; add --force for unattended workflows:

Explicit module versions continue to be supported, including versions resolved during updates:

Module dependencies declared in a module's box.json are installed automatically as nested modules inside the parent module's modules/ folder. See Module Dependencies and Nested Modules.

Upgrading Your Install

The install-boxlang script will allow you to upgrade your OS installation easily. If you call it without arguments, it will install the latest stable release and override the local install. You can also pass a specific version to install as the second argument, or the word snapshotto install the bleeding edge release. You can find all the latest artifacts here: https://downloads.ortussolutions.com/#/ortussolutions/boxlang/

Installing Modules

Use the bx-module command to install modules into your BoxLang home. Pass the slug of the module you want, or several slugs at once.

All our modules are available in the cloud software directory FORGEBOX. You can also register and collaborate with modules of your own 🙋.

Install in the BoxLang Home

Install Locally

You can also install modules to the running application (CLI, web) by using the --local option in the command. This will create a boxlang_modules folder where you ran the command and install the modules there.

Modules

BoxLang Version Manager (BVM)

BVM is a simple version manager for BoxLang, similar to jenv or nvm. It allows you to easily install, manage, and switch between different versions of BoxLang. Read the full documentation at the link below:

BoxLang Version Manager (BVM)

To get started easily, just follow the instructions:

Just copy the following into your terminal to install by default for your user.

Coming Soon

R.E.P.L.

Read, Evaluate, Print Loop

A REPL, or Read-Evaluate-Print Loop, is an interactive programming environment that takes single-user inputs, executes them, and returns the result to the user. This is particularly useful for testing code snippets and debugging in real time. In the context of BoxLang, running boxlang will start the REPL, allowing you to write and test code quickly within the BoxLang environment.

The REPL will also remember state, so you can define variables and use them in your testing and explorations. Code away 🚀

Binaries

The quick installer is the best and easiest way to get installed on Mac or *Nix. However, below, you can find a collection of all our installers and binaries for running BoxLang and each Runtime.

Operating System Binaries

Here, you can find the installers and binaries for all Operating Systems:

MiniServer Binaries

The BoxLang MiniServer includes the BoxLang OS runtime with the addition of our super-fast and lightweight web server.

AWS Lambda Binaries

BoxLang can also run on AWS Lambdas. It even powers our entry playground at https://try.boxlang.io.

Google Cloud Functions Runtime

BoxLang can also run on Google Cloud Functions using our Java 21 runtime integration.

Azure Functions Runtime

BoxLang can also run on Azure Functions using our Java 21 runtime integration.

CommandBox BoxLang Server

BoxLang can also be deployed using CommandBox. This is our preferred way to deploy web applications using BoxLang. BoxLang +/++ Subscribers even get access to CommandBox Pro. Note: This installation method is typically tailored for a specific web application and is not typically accessible by other applications.

Learn more in our CommandBox guide.

Servlet EE Binaries

This is the servlet edition of BoxLang that you can deploy on any servlet container (Jetty, Tomcat, JBoss, etc)

Spring Boot Starter

The BoxLang Spring Boot Starter allows you to use BoxLang as a view engine and runtime inside any Spring Boot 3 web application.

Docker

BoxLang IDE & Tools

BoxLang provides officially supported tooling for popular IDEs to enhance your development experience.

BoxLang IDE for VSCode

VSCode Extension

The BoxLang IDE for VSCode is a collection of tools that gives you a line debugger, LSP (Language Server Protocol), highlighting, introspection, generation, and much more. You can find it here:

Install VSCode IDE

IntelliJ IDEA Plugin

We also have a robust plugin for IntelliJ IDEA and other JetBrains IDEs. It provides syntax highlighting, auto-completion, formatting, and debugging capabilities for your BoxLang projects.

Install IntelliJ Plugin

Learn more about all the available tools in our IDE & Tooling Section.

Core Modules

The BoxLang core is lightweight and fast. Everything that extends the core comes as modules or individual runtimes. We have a collection of core modules that the BoxLang team maintains and curates. We also have several enterprise modules for our BoxLang +, ++ subscribers, and the community can create and share modules in our cloud package manager FORGEBOX.

Modules

BoxLang+, ++ Modules

Our BoxLang+, and ++ subscribers not only get professional/customized support but also new features, and modules. You can find out more about our subscriptions here: https://boxlang.io/plans. Here is the collection of modules that you will get with your subscription which are not part of the open source edition.

+Modules
Module
Description
Status

Azure Key Vault integration for getSystemSetting() using the azure. namespace.

Done

AWS Secrets Manager integration for getSystemSetting() using the aws. namespace.

Done

Google Secret Manager integration for getSystemSetting() using the google. namespace.

Done

Streaming CSV parsing & generation for large datasets

Done

Native Couchbase integration for caching, NoSQL, session distribution and advanced Couchbase usage.

Done

A comprehensive LDAP module for BoxLang that brings full-featured LDAP directory access to your applications.

Done

Subscription bootstrap, entitlement validation, shared utilities

Done

PDF generation and manipulation for documents, reports, and forms. Includes free-tier and licensed functionality.

Done

Native Redis integration is used for caching, session distribution, and publish-subscribe events.

Done

REST component compatibility and routing translation layer for running legacy framework-less REST architectures.

Done

Read, write, and style spreadsheet documents (XLSX).

Done

SOAP compatibility layer for generating, parsing, and communicating with web services.

Done

Read, write, and style Word documents (DOCX).

Done

Last updated

Was this helpful?