= Install Clojure
Alex Miller
2021-01-21
:type: guides
:toc: macro
:icons: font

ifdef::env-github,env-browser[:outfilesuffix: .adoc]

toc::[]

== Intro

Clojure (the language) is provided as a Java ARchive (JAR) file, available in the https://maven.apache.org/repository/[Maven Central Repository], a public repository for JVM-based artifacts. If needed, you can find more detailed version information on the <<xref/../../../releases/downloads#,Releases>> page.

This page concerns the command-line tool (the Clojure CLI). This tool (used by the commands `clojure` and `clj`) can download Clojure itself and other Clojure or JVM-based libraries. **Any version of the Clojure CLI can download or use any version of the Clojure language itself (they are independent).**

The version numbers of the language and the CLI are separate but related. The Clojure language has a 3 part-version (like `1.12.0`) and the Clojure CLI has a 4-part version (like `1.12.0.1456`). The leading 3 parts of the CLI version indicate which version of the Clojure language will be used by default in a REPL, unless you specify otherwise in the <<xref/../../../reference/deps_edn#,deps.edn>> configuration file.

== Mac OS instructions

Prerequisites: <<install_clojure#java,Java>>, <<install_clojure#brew,brew>>

This adds the commands `clojure` and `clj` to your system from the https://github.com/clojure/homebrew-tools[clojure/tools tap]:

[source,shell]
----
brew install clojure/tools/clojure
----

If you already have the CLI installed, you can use this command to upgrade to the latest version:

[source,shell]
----
brew upgrade clojure/tools/clojure
----

== Linux instructions

Prerequisites: <<install_clojure#java,Java>>, `bash`, `curl`, `rlwrap`

To install with the Linux script installer:

1. Ensure that the following dependencies are installed: `bash`, `curl`, `rlwrap`, and `Java`.
2. Use the `linux-install` script to download and run the install, which will create the executables `/usr/local/bin/clj`, `/usr/local/bin/clojure`, and the directory `/usr/local/lib/clojure`:

[source,shell]
----
curl -L -O https://github.com/clojure/brew-install/releases/latest/download/linux-install.sh
chmod +x linux-install.sh
sudo ./linux-install.sh
----

To install to a custom location (like `/opt/infrastructure/clojure`), use the option `--prefix`:

[source,shell]
----
sudo ./linux-install.sh --prefix /opt/infrastructure/clojure
----

You may also want to extend the MANPATH in `/etc/man_db.conf` to include the manual pages:

[source]
----
MANPATH_MAP /opt/infrastructure/clojure/bin /opt/infrastructure/clojure/man
----

The `linux-install` script can be removed after installation.

== Posix instructions

A POSIX version of the linux installer is now available as well. This installer should work on Linux, BSD, and even Mac (but will conflict with brew!)

To install with the POSIX script installer:

1. Ensure that the following dependencies are installed: `bash`, `curl`, `rlwrap`, and `Java`.
2. Use the `posix-install` script to download and run the install, which will create the executables `/usr/local/bin/clj`, `/usr/local/bin/clojure`, and the directory `/usr/local/lib/clojure`:

[source,shell]
----
curl -L -O https://github.com/clojure/brew-install/releases/latest/download/posix-install.sh
chmod +x posix-install.sh
sudo ./posix-install.sh
----

To install to a custom location (like `/opt/infrastructure/clojure`), use the option `--prefix`:

[source,shell]
----
sudo ./posix-install.sh --prefix /opt/infrastructure/clojure
----

You may also want to extend the MANPATH in `/etc/man_db.conf` to include the manual pages:

[source]
----
MANPATH_MAP /opt/infrastructure/clojure/bin /opt/infrastructure/clojure/man
----

The `posix-install` script can be removed after installation.

== Windows instructions

Prerequisites: <<install_clojure#java,Java>>

=== Windows Subsystem for Linux (WSL)

If you are not yet using https://learn.microsoft.com/en-us/windows/wsl/install[WSL] (Windows Subsystem for Linux), this is recommended as it will provide the closest match for most existing Clojure tutorials and documentation.

Once you have installed WSL, follow the <<install_clojure#_linux_instructions,Linux installation instructions>> and proceed from there.

=== Windows Installer

Alternately, you can use https://github.com/casselc/clj-msi[clj-msi] to install clojure.exe on your system, which can be used in similar ways to the `clojure` script installed in the other approaches above.

== Prerequisite installation details

[[brew]]
=== brew (Mac or Linux)

`brew` is a package manager for Mac OS X or Linux. To install `brew`:

* Go to https://brew.sh/ and follow the installation instructions for your OS

[[java]]
=== Java

Clojure requires Java. Clojure officially supports Java LTS releases (currently Java 8, 11, 17 and 21), but also tries to ensure interim versions work as well. You can use any Java distribution, whether it’s a commercial release from Oracle or an open source version based on OpenJDK (like Temurin). The Clojure tools require only that the `java` command is on the `PATH` or that the `JAVA_HOME` environment variable is set.

If you don't already hava Java installed, we recommend installing Adoptium Temurin 21.

To use the Adoptium Temurin installers:

* Go to https://adoptium.net/
* Download and run the installer appropriate to your platform
* Ensure `java` is on the system PATH

On Mac, you can also install Temurin using brew:

* `brew install --cask temurin@21` - install Temurin 21 (formerly AdoptOpenJDK)

Check your Java version by running `java --version`. If that's not Temurin 21, then you may then need to add `java` to your `PATH`:

[source,shell]
----
echo 'export PATH="/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home/bin:$PATH"' >> ~/.zshrc
----

== Installing archive or prerelease versions of the CLI

For other versions of the Clojure CLI, see the <<xref/../../releases/tools#,changelog>> for version history and the https://github.com/clojure/homebrew-tools[Clojure tap] for info on installing older versions or newer prereleases instead.
