Home

Awesome

<img src="logo/babashka.svg" alt="Babashka" width="425px">

CircleCI project chat Financial Contributors on Open Collective Clojars Project twitter docs Gurubase

<blockquote class="twitter-tweet" data-lang="en"> <p lang="en" dir="ltr">Life's too short to remember how to write Bash code. I feel liberated.</p> &mdash; <a href="https://github.com/laheadle">@laheadle</a> on Clojurians Slack </blockquote>

Introduction

Babashka is a native Clojure interpreter for scripting with fast startup. Its main goal is to leverage Clojure in places where you would be using bash otherwise.

As one user described it:

I’m quite at home in Bash most of the time, but there’s a substantial grey area of things that are too complicated to be simple in bash, but too simple to be worth writing a clj/s script for. Babashka really seems to hit the sweet spot for those cases.

Goals

Non-goals

Quickstart

For installation options check Installation. For quick installation using bash, use:

bash < <(curl -s https://raw.githubusercontent.com/babashka/babashka/master/install)

or grab a binary from Github releases yourself and place it anywhere on the path.

Then you're ready to go:

time bb -e '(->> (fs/list-dir ".") (filter fs/directory?) (map fs/normalize) (map str) (take 3))'

(".build" "feature-lanterna" ".repl")
bb -e    0,01s  user 0,01s system 70% cpu 0,017 total

Support :heart:

You can support this project via Github Sponsors, OpenCollective, Ko-fi or indirectly via Clojurists Together.

<details> <summary>Top sponsors</summary> </details>

Babashka users

See companies for a list of companies using babashka.

Are you using babashka in your company or personal projects? Let us know here.

Setting expectations

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.

Status

Functionality regarding clojure.core and java.lang can be considered stable and is unlikely to change. Changes may happen in other parts of babashka, although we will try our best to prevent them. Always check the release notes or CHANGELOG.md before upgrading.

Talk

To get an overview of babashka, you can watch this talk (slides):

Babashka at ClojureD 2020

Babashka book

The babashka book contains detailed information about how to get the most out of babashka scripting.

There is also the book Babashka Babooka, by Daniel Higginbotham, who has also helped a lot of people learn Clojure with Clojure for the Brave and True.

Try online

You can try babashka online with Nextjournal's babashka notebook environment.

Installation

Brew

Linux and macOS binaries are provided via brew.

Install:

brew install borkdude/brew/babashka

Upgrade:

brew upgrade babashka

Nix

Linux and macOS (including ARM Macs) binaries are provided via nix (see the installation instructions for nix here).

Install:

# Adding `nixpkgs-unstable` channel for more up-to-date binaries, skip this if you already have `nixpkgs-unstable` in your channel list
nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgs-unstable
nix-channel --update
nix-env -iA nixpkgs-unstable.babashka

Upgrade:

nix-channel --update
nix-env -iA nixpkgs-unstable.babashka

You can find more documentation on how to use babashka with nix here.

Alpine

On Alpine it's recommended to download the binary manually from Github Releases and use the static linux binary.

Arch (Linux)

babashka is available in the Arch User Repository. It can be installed using your favorite AUR helper such as yay, yaourt, apacman and pacaur. Here is an example using yay:

yay -S babashka-bin

asdf

asdf is an extendable version manager for linux and macOS. Note that asdf will add significant startup time to any babashka script, consider using mise instead.

Babashka can be installed using a plugin as follows:

asdf plugin add babashka https://github.com/pitch-io/asdf-babashka
asdf install babashka latest

mise

mise is a development environment setup tool for linux and macOS.

Install:

mise use --global babashka@latest

Upgrade:

mise upgrade babashka

Windows

Scoop

On Windows you can install using scoop and the scoop-clojure bucket.

Or just follow these concrete steps:

# Note: if you get an error you might need to change the execution policy (i.e. enable Powershell) with
# Set-ExecutionPolicy RemoteSigned -scope CurrentUser
Invoke-Expression (New-Object System.Net.WebClient).DownloadString('https://get.scoop.sh')

scoop bucket add scoop-clojure https://github.com/littleli/scoop-clojure
scoop bucket add extras
scoop install babashka

Manual

If scoop does not work for you, then you can also just download the bb.exe binary from Github releases and place it on your path manually.

WSL1

Note: WSL1 users might experience a BSOD, please use the --static install option when installing

$ curl -sLO https://raw.githubusercontent.com/babashka/babashka/master/install
$ chmod +x install
$ ./install --static

Installer script

Install via the installer script for linux and macOS:

$ curl -sLO https://raw.githubusercontent.com/babashka/babashka/master/install
$ chmod +x install
$ ./install

By default this will install into /usr/local/bin (you may need sudo for this). To change this, provide the directory name:

$ ./install --dir .

To install a specific version, the script also supports --version:

$ ./install --dir . --version 0.4.1

To force the download of the zip archive to a different directory than /tmp use the --download-dir argument:

$ ./install --dir . --version 0.4.1 --download-dir .

On Linux, if you want to install the static binary version:

$ ./install --dir . --version 0.4.1 --download-dir . --static

In case you want to check the download, you can use the --checksum option. This maybe useful for unattended installations:

$ sha256sum babashka-0.4.1-linux-amd64-static.tar.gz
ab70fb39fdbb5206c0a2faab178ffb54dd9597991a4bc13c65df2564e8f174f6  babashka-0.4.1-linux-amd64-static.tar.g
$ ./install --dir /tmp --checksum ab70fb39fdbb5206c0a2faab178ffb54dd9597991a4bc13c65df2564e8f174f6 --static --version 0.4.1

Note that the --checksum option only works when --version option is also provided. This is to avoid breakage when a new version of Babashka is released.

Github releases

You may also download a binary from Github. For linux there is a static binary available which can be used on Alpine.

CI

Docker

Check out the image on Docker hub.

News

Check out the news page to keep track of babashka-related news items.

Built-in namespaces

Go here to see the full list of built-in namespaces.

Compatible Projects

A list of projects (scripts, libraries, pods and tools) known to work with babashka.

Badges

<!-- note to editor: it seems a blank line must appear before code blocks within <details> -->

bb compatible

The babashka compatible badge indicates that a library can be used as babashka dependency.

If this is the case for your library, we encourage you to proudly display this badge.

<details><summary>Markdown</summary> 
[![bb compatible](https://raw.githubusercontent.com/babashka/babashka/master/logo/badge.svg)](https://babashka.org)
</details> <details><summary>AsciiDoc</summary> 
https://babashka.org[image:https://raw.githubusercontent.com/babashka/babashka/master/logo/badge.svg[bb compatible]]
</details> <details><summary>HTML</summary> 
<a href="https://babashka.org" rel="nofollow"><img src="https://github.com/babashka/babashka/raw/master/logo/badge.svg" alt="bb compatible" style="max-width: 100%;"></a>
</details> <br/>

bb built-in

The babashka built-in badge means that a library has been built directly into babashka and requires no extra dependencies to use it.

If this rare honor belongs to your library, you should display this badge.

<details><summary>Markdown</summary> 
[![bb built-in](https://raw.githubusercontent.com/babashka/babashka/master/logo/built-in-badge.svg)](https://babashka.org)
</details> <details><summary>AsciiDoc</summary> 
https://babashka.org[image:https://raw.githubusercontent.com/babashka/babashka/master/logo/built-in-badge.svg[bb built-in]]
</details> <details><summary>HTML</summary> 
<a href="https://babashka.org" rel="nofollow"><img src="https://github.com/babashka/babashka/raw/master/logo/built-in-badge.svg" alt="bb built-in" style="max-width: 100%;"></a>
</details> </br>

Swag

Pods

Pods are programs that can be used as a Clojure library by babashka. Documentation is available in the pod library repo.

A list of available pods can be found in the pod registry.

Differences with Clojure

Babashka is implemented using the Small Clojure Interpreter. This means that a snippet or script is not compiled to JVM bytecode, but executed form by form by a runtime which implements a substantial subset of Clojure. Babashka is compiled to a native binary using GraalVM. It comes with a selection of built-in namespaces and functions from Clojure and other useful libraries. The data types (numbers, strings, persistent collections) are the same. Multi-threading is supported (pmap, future).

Differences with Clojure:

Package babashka script as a AWS Lambda

AWS Lambda runtime doesn't support signals, therefore babashka has to disable handling of SIGINT and SIGPIPE. This can be done by setting BABASHKA_DISABLE_SIGNAL_HANDLERS to true.

Articles, podcasts and videos

Building babashka

Developing Babashka

Including new libraries or classes

Before new libraries or classes go into the standardly distributed babashka binary, these evaluation criteria are considered:

If not all of the criteria are met, but adding a feature is still useful to a particular company or niche, adding it behind a feature flag is still a possibility. This is currently the case for next.jdbc and the PostgresQL and HSQLDB database drivers. Companies interested in these features can compile an instance of babashka for their internal use. Companies are also free to make forks of babashka and include their own internal libraries. If their customized babashka is interesting to share with the world, they are free to distribute it using a different binary name (like bb-sql, bb-docker, bb-yourcompany, etc.). See the feature flag documentation and the implementation of the existing feature flags (example commit).

Related projects

Contributors

Thanks to all the people that contributed to babashka:

License

Copyright © 2019-2020 Michiel Borkent

Distributed under the EPL License. See LICENSE.

This project contains code from: