Babashka book

Babashka is written for developers who are familiar with Clojure on the JVM. This book assumes familiarity with Clojure and is not a Clojure tutorial. If you aren’t that familiar with Clojure but you’re curious to learn, check out this list of beginner resources.

Babashka uses SCI for interpreting Clojure. SCI implements a substantial subset of Clojure. Interpreting code is in general not as performant as executing compiled code. If your script takes more than a few seconds to run or has lots of loops, Clojure on the JVM may be a better fit, as the performance on JVM is going to outweigh its startup time penalty. Read more about the differences with Clojure here.

Installing babashka is as simple as downloading the binary for your platform and placing it on your path. Pre-built binaries are provided on the releases page of babashka’s Github repo. Babashka is also available in various package managers like brew for macOS and linux and scoop for Windows. See here for details.

If you would rather build babashka from source, download a copy of GraalVM and set the GRAALVM_HOME environment variable. Also make sure you have lein installed. Then run:

See the babashka build.md page for details.

The babashka executable is called bb. You can either provide it with a Clojure expression directly:

or run a script:

The -e flag is optional when the argument starts with a paren. In that case babashka will treat it automatically as an expression:

Similarly, the -f flag is optional when the argument is a filename:

Commonly, scripts have shebangs so you can invoke them with their filename only:

Scripts may be executed from a file using -f or --file:

The file may also be passed directly, without -f:

Using bb with a shebang also works:

If /usr/bin/env doesn’t work for you, you can use the following workaround:

The var *file* contains the full path of the file that is currently being executed:

Command-line arguments can be retrieved using *command-line-args*. If you want to parse command line arguments, you can use the built-in babashka.cli namespace:

Note that clojure.tools.cli is also built-in to babashka.

It is recommended to use bb.edn to control what directories and libraries are included on babashka’s classpath. See Project setup

If you want a lower level to control babashka’s classpath, without the usage of bb.edn you can use the --classpath option that will override the classpath. Say we have a file script/my/namespace.clj:

Now we can execute this main function with:

If you have a larger script with a classic Clojure project layout like

then you can tell babashka to include both the src and test folders in the classpath and start a socket REPL by running:

If there is no --classpath argument, the BABASHKA_CLASSPATH environment variable will be used. If that variable isn’t set either, babashka will use :deps and :paths from bb.edn.

Also see the babashka.classpath namespace which allows dynamically adding to the classpath.

The namespace babashka.deps integrates tools.deps with babashka and allows you to set the classpath using a deps.edn map.

A main function can be invoked with -m or --main like shown above. When given the argument foo.bar, the namespace foo.bar will be required and the function foo.bar/-main will be called with command line arguments as strings.

Since babashka 0.3.1 you may pass a fully qualified symbol to -m:

so you can execute any function as a main function, as long as it accepts the number of provided arguments.

When invoking bb with a main function, the expression (System/getProperty "babashka.main") will return the name of the main function.

The environment variable BABASHKA_PRELOADS allows to define code that will be available in all subsequent usages of babashka.

Note that you can concatenate multiple expressions. Now you can use these functions in babashka:

You can also preload an entire file using load-file:

Note that *input* is not available in preloads.

Babashka supports running a REPL, a socket REPL and an nREPL server.

In one-liners the *input* value may come in handy. It contains the input read from stdin as EDN by default. If you want to read in text, use the -i flag, which binds *input* to a lazy seq of lines of text. If you want to read multiple EDN values, use the -I flag. The -o option prints the result as lines of text. The -O option prints the result as lines of EDN values.

The following table illustrates the combination of options for commands of the form

When combined with the --stream option, the expression is executed for each value in the input:

The --uberscript option collects the expressions in BABASHKA_PRELOADS, the command line expression or file, the main entrypoint and all required namespaces from the classpath into a single file. This can be convenient for debugging and deployment.

Here is an example that uses a function from the clj-commons/fs library.

Let’s first set the classpath:

Write a little script, say glob.clj:

For testing, we’ll make a file which we will find using the glob function:

Now we can execute the script which uses the library:

Producing an uberscript with all required code:

To prove that we don’t need the classpath anymore:

Caveats:

If any of the above is problematic for your project, using an uberjar is a good alternative.

Babashka can create uberjars from a given classpath and optionally a main method:

Babashka sets the following system properties:

Data readers can be enabled by setting *data-readers* to a hashmap of symbols to functions or vars:

To preserve good startup time, babashka does not scan the classpath for data_readers.clj files.

Babashka supports reader conditionals by taking either the :bb or :clj branch, whichever comes first. NOTE: the :clj branch behavior was added in version 0.0.71, before that version the :clj branch was ignored.

Babashka bundles deps.clj for invoking a clojure JVM process:

See the clojure function in the babashka.deps namespace for programmatically invoking clojure.

Since version 0.3.1, babashka supports a local bb.edn file to manage a project.

You can declare one or multiple paths and dependencies so they are automatically added to the classpath:

If we have a project that has a deps.edn and would like to reuse those deps in bb.edn:

bb.edn applies to the local project, and dependencies defined in this files are never shared with other projects. This is typically what you want when writing a script or tool. By contrast, deps.edn is useful when creating libraries that are used by other projects.

If we have a main function in a file called bb/my_project/main.clj like:

we can invoke it like:

See Invoking a main function for more details on how to invoke a function from the command line.

The :deps entry is managed by deps.clj and requires a java installation to resolve and download dependencies.

Since version 0.3.6, babashka supports the :min-bb-version where the minimal babashka version can be declared:

When using an older bb version (that supports :min-bb-version), babashka will print a warning:

Since babashka 0.4.0 the bb.edn file supports the :tasks entry which describes tasks that you can run in the current project. The tasks feature is similar to what people use Makefile, Justfile or npm run for. See Task runner for more details.

Since babashka 1.3.177 a bb.edn file relative to the invoked file is respected. This makes writing system-global scripts with dependencies easier.

Given a bb.edn:

and a script medley.bb:

Assuming that medley.bb is executable (chmod +x medley.bb), you can directly execute it in the current directory:

To execute this script from anywhere on the system, you just have to add it to the PATH:

Of course you can just call your script medley without the .bb extension.

People often use a Makefile, Justfile, npm scripts or lein aliases in their (clojure) projects to remember complex invocations and to create shortcuts for them. Since version 0.4.0, babashka supports a similar feature as part of the bb.edn project configuration file. For a general overview of what’s available in bb.edn, go to Project setup.

The tasks configuration lives under the :tasks key and can be used together with :paths and :deps:

In the above example we see a simple task called clean which invokes the shell command, to remove the target directory. You can invoke this task from the command line with:

Babashka also accepts a task name without explicitly mentioning run:

To make your tasks more cross-platform friendly, you can use the built-in babashka.fs library. To use libraries in tasks, use the :requires option:

Tasks accept arbitrary Clojure expressions. E.g. you can print something when executing the task:

Go here if you would like to watch a talk on babashka tasks.

Instead of naked expressions, tasks can be defined as maps with options. The task expression should then be moved to the :task key:

Tasks support the :doc option which gives it a docstring which is printed when invoking bb tasks on the command line. Other options include:

When invoking bb tasks, babashka prints a list of all tasks found in bb.edn in the order of appearance. E.g. in the clj-kondo.lsp project it prints:

Command line arguments are available as *command-line-args*, just like in Clojure. Since version 0.9.160, you can use babashka.cli in tasks via the exec function to deal with command line arguments in a concise way. See the chapter on babashka CLI.

Of course, you are free to parse command line arguments using the built-in tools.cli library or just handle them manually.

You can re-bind *command-line-args* to ensure functions see a different set of arguments:

You can execute tasks using bb <task-name>. The babashka run subcommand can be used to execute with some additional options:

The task runner exposes the following hooks:

The babashka.tasks namespace exposes the following functions: run, shell, clojure and current-task. They are implicitly imported, thus available without a namespace prefix.

Dependencies between tasks can be declared using :depends:

The fs/modified-since function returns a seq of all newer files compared to a target, which can be used to prevent rebuilding artifacts when not necessary.

Alternatively you can use the :init hook to define vars, require namespaces, etc.:

It is common to define tasks that only serve as a helper to other tasks. To not expose these tasks in the output of bb tasks, you can start their name with a hyphen.

The :parallel option executes dependencies of the invoked task in parallel (when possible). This can be used to speed up execution, but also to have multiple tasks running in parallel for development:

Invoking a main function can be done by providing a fully qualified symbol:

You can use any fully qualified symbol, not just ones that end in -main (so e.g. foo.bar/baz is fine). You can also have multiple main functions in one namespace.

The namespace foo.bar will be automatically required and the function will be invoked with *command-line-args*:

To get a REPL within a task, you can use clojure.main/repl:

Alternatively, you can use babashka.tasks/run to invoke a task from a REPL.

For REPL- and linting-friendliness, it’s recommended to move task code longer than a couple of lines to a .clj or .bb file.

Because bb.edn is an EDN file, you cannot use all of Clojure’s syntax in expressions. Most notably:

For invoking functions from the command line, you can use the new -x flag (a pun to Clojure’s -X of course!):

What we see in the above snippet is that a map {:hello "there"} is constructed by babashka CLI and then fed to the prn function. After that the result is printed to the console.

What if we want to influence how things are parsed by babashka CLI and provide some defaults? This can be done using metadata. Let’s create a bb.edn and make a file available on the classpath:

bb.edn:

tasks.clj:

Now let’s invoke:

As you can see, the namespace options are merged with the function options. Defaults can be provided with :exec-args, like you’re used to from the clojure CLI.

What about task integration? Let’s adapt our bb.edn:

and invoke the task:

As you can see it works similar to -x, but you can provide another set of defaults on the task level with :exec-args. Executing a function through babashka CLI is done using the babashka.task/exec function, available by default in tasks.

To add :exec-args that should be evaluated you can pass an extra map to exec as follows:

Help people who use babashka know that your library works with babashka.

Add the babashka compatible badge if your library works as a babashka dependency. Let the world know by adding this badge to your project’s README:

Add the babashka built-in badge if your library has the rare honor of being built into babashka. Add this badge to your project’s README:

In addition to clojure.core, the following libraries / namespaces are available in babashka. Some are available through pre-defined aliases in the user namespace, which can be handy for one-liners. If not all vars are available, they are enumerated explicitly. If some important var is missing, an issue or PR is welcome.

From Clojure:

Additional libraries:

Check out the babashka toolbox and projects page for libraries that are not built-in, but which you can load as an external dependency in bb.edn.

See the build page for built-in libraries that can be enabled via feature flags, if you want to compile babashka yourself.

A selection of Java classes are available, see babashka/impl/classes.clj in babashka’s git repo.

Babashka is able to run Clojure projects from source, if they are compatible with the subset of Clojure that sci is capable of running.

Check this page for projects that are known to work with babashka.

Since bb 0.2.6 pods can be obtained via the pod-registry.

This is an example script which uses the fswatcher pod to watch a directory for changes:

Since bb 0.8.0 pods can be declared in bb.edn:

Given the file bb/my_project/db.clj:

you can then execute the main function, without calling load-pod manually:

Use explicit requires with namespace aliases in scripts, unless you’re writing one-liners.

Do this:

But not this:

script.clj:

Rather do this:

script.clj:

Some reasons for this:

Babashka bundles clojure.test. To run tests you can write a test runner script. Given the following project structure:

In Python scripts there is a well-known pattern to check if the current file was the file invoked from the command line, or loaded from another file: the __name__ == "__main__" pattern. In babashka this pattern can be implemented with:

Combining this with a conditional invocation of -main creates a script file that is safe to load at a REPL, and easy to invoke at the CLI.

This can be exceedingly handy for editing complex scripts interactively, while not being able to adjust how they are invoked by other tools.

Adding a shutdown hook allows you to execute some code before the script exits.

This also works when the script is interrupted with ctrl-c.

Babashka doesn’t print a returned nil as lots of scripts end in something side-effecting.

If you really want to print the nil, you can use (prn ..) instead.

In addition to future, pmap, promise and friends, you may use the clojure.core.async namespace for asynchronous scripting. The following example shows how to get first available value from two different processes:

Caveat: currently the go macro is available for compatibility with JVM programs, but the implementation maps to clojure.core.async/thread and the single exclamation mark operations (<!, >!, etc.) map to the double exclamation mark operations (<!!, >!!, etc.). It will not "park" threads, like on the JVM.

Examples like the following may still work, but will take a lot more system resources than on the JVM and will break down for some high value of n:

Babashka comes with the nrepl/bencode library which allows you to read and write bencode messages to a socket. A simple example which evaluates a Clojure expression on an nREPL server started with lein repl:

On Windows, bb can be invoked from the bash shell directly:

However, creating a script that invokes bb via a shebang leads to an error if the script is not in the current directory. Suppose you had the following script named hello on your path:

The problem here is that the shell is passing a Cygwin-style path to bb, but bb can’t recognize it because it wasn’t compiled with Cygwin.

The solution is to create a wrapper script that converts the Cygwin-style path to a Windows-style path before invoking bb. Put the following into a script called bbwrap somewhere on your Cygwin path, say in /usr/local/bin/bbwrap:

Make sure to fix your original script to invoke bbwrap instead of bb directly: