Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/antlobach/clorch/llms.txt

Use this file to discover all available pages before exploring further.

Clorch is distributed as a git dependency and pulls its native PyTorch binaries through JavaCPP. There is no separate native install step for CPU usage — the JVM downloads and caches the right platform binaries on the first run. GPU support requires additional system packages and a compatible NVIDIA driver, which are covered below.
1
Add Clorch to deps.edn
2
Create a Clojure project directory and add the following deps.edn. The git coordinates pin Clorch to the v0.2.0 release:
3
{:paths ["src"]
 :deps {io.github.antlobach/clorch
        {:git/tag "v0.2.0"
         :git/sha "07642acdbc522e8aa2a20cd223912247614d2239"}}}
4
Verify your runtime
5
Clorch is tested across a full Java 21–25 matrix. Confirm your environment matches the supported stack before starting:
6
ComponentSupported versionJavaOpenJDK / Temurin 21 through 25Clojure1.12.xClojure CLI1.12.x (CI uses 1.12.5.1664)Native PyTorchJavaCPP PyTorch 2.10.0-1.5.13
7
Java 21 ┐
Java 22 │
Java 23 ├─ PyTorch 2.10 + JavaCPP 1.5.13 CPU natives
Java 24 │
Java 25 ┘
8
Java 24 and 25 require the --enable-native-access=ALL-UNNAMED JVM flag for JavaCPP to load native libraries. Without it, the JVM may refuse to load the LibTorch bindings. See the REPL startup steps below for how to set this flag automatically.
9
Start the REPL (CPU)
10
From your project directory, launch the Clojure REPL:
11
clj
12
On Java 24 or 25 you must pass the native-access flag:
13
clj -J--enable-native-access=ALL-UNNAMED
14
Setting JAVA_TOOL_OPTIONS in your shell profile is the most convenient approach if you use Java 24+ regularly:
15
export JAVA_TOOL_OPTIONS="--enable-native-access=ALL-UNNAMED"
clj
16
Select a backend
17
Clorch detects the backend automatically when clorch.torch loads. It uses CUDA when GPU natives are available and NVIDIA hardware is detected; otherwise it loads the CPU backend.
18
You can override automatic detection with environment variables:
19
VariableEffect(unset)Automatic: CUDA if available, otherwise CPUCLORCH_FORCE_CPU=1Forces the CPU backend regardless of hardwareCLORCH_FORCE_GPU=1Requests the CUDA backend; still requires compatible libraries and an NVIDIA driver
20
Install GPU system packages (CUDA only)
21
GPU support requires Java 25, CUDA 13.1, cuDNN 9.19, and NCCL 2.29.2. The validated hardware is 2× RTX A5000 on a Linux host.
22
Use a JDK, not a JRE. On Ubuntu with NVIDIA’s CUDA package repository configured:
23
sudo apt-get update
sudo apt-get install cuda-libraries-13-1 libcudnn9-cuda-13 libnccl2
24
Confirm that the host exposes each GPU before starting Clojure:
25
nvidia-smi -L
java -version
clojure -Sdescribe
26
Set environment variables and start the GPU REPL
27
Set native-loading variables before the JVM starts. JAVA_TOOL_OPTIONS is inherited by launcher-created worker JVMs, which is important for distributed training:
28
export CLORCH_FORCE_GPU=1
export LD_LIBRARY_PATH="/usr/local/cuda/lib64:${LD_LIBRARY_PATH:-}"
export JAVA_TOOL_OPTIONS="--enable-native-access=ALL-UNNAMED"

CLOJURE_DISABLE_RLWRAP=1 clojure -M:dev
29
Verify CUDA from the REPL
30
Once the REPL is running, confirm that CUDA is visible:
31
(require '[clorch.cuda :as cuda]
         '[clorch.torch :as t])

{:available (cuda/available?)
 :devices   (cuda/device-count)}
;; => {:available true, :devices 2}

​
Multi-GPU Requirements

Distributed training uses one worker JVM per GPU and NCCL for inter-process communication. The full validated stack for multi-GPU work is: 
Java 25
PyTorch / LibTorch 2.10
JavaCPP 1.5.13
CUDA 13.1
cuDNN 9.19
NCCL 2.29.2
2× RTX A5000
Additional runtime requirements:
  • Two or more NVIDIA GPUs visible to the same Linux host
  • A working NVIDIA driver with CUDA 13 support
  • One distinct CUDA device per rank
  • Enough host RAM and CUDA VRAM for one model replica per rank
  • A writable checkpoint directory and an available local TCP port
Read the Distributed CUDA Training guide for worker code, NCCL collectives, DDP, AMP, gradient accumulation, and checkpoint restore.

​
nREPL Dev Server

The repository’s deps.edn includes a :dev alias that starts an nREPL server. Clone the repository and run: 
clj -M:dev
The nREPL server listens on 127.0.0.1:7891 by default. Override the port or bind address with environment variables:
VariableDefaultEffect
CLORCH_NREPL_PORT7891Port the nREPL server binds to
CLORCH_NREPL_BIND127.0.0.1Interface address the server listens on
When working with the repository examples, use clj -M:dev rather than plain clj so that the examples/ directory is on the classpath and example namespaces like distributed-training and pytorch-basics-tutorial can be required directly.

Build docs developers (and LLMs) love

Get started for freeTalk to us