> ## Documentation Index
> Fetch the complete documentation index at: https://antlobach-clorch-182a83cb.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing Clorch and Configuring CPU or CUDA Backends

> Set up Clorch via git coordinates in deps.edn, choose between CPU and CUDA backends, install GPU system packages, and launch an nREPL dev server.

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.

<Steps>
  ### Add Clorch to `deps.edn`

  Create a Clojure project directory and add the following `deps.edn`. The git coordinates pin Clorch to the `v0.2.0` release:

  ```clojure theme={null}
  {:paths ["src"]
   :deps {io.github.antlobach/clorch
          {:git/tag "v0.2.0"
           :git/sha "07642acdbc522e8aa2a20cd223912247614d2239"}}}
  ```

  ### Verify your runtime

  Clorch is tested across a full Java 21–25 matrix. Confirm your environment matches the supported stack before starting:

  | Component | Supported version |
  | - | - |
  | Java | OpenJDK / Temurin 21 through 25 |
  | Clojure | 1.12.x |
  | Clojure CLI | 1.12.x (CI uses `1.12.5.1664`) |
  | Native PyTorch | JavaCPP PyTorch `2.10.0-1.5.13` |

  ```text theme={null}
  Java 21 ┐
  Java 22 │
  Java 23 ├─ PyTorch 2.10 + JavaCPP 1.5.13 CPU natives
  Java 24 │
  Java 25 ┘
  ```

  <Note>
    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.
  </Note>

  ### Start the REPL (CPU)

  From your project directory, launch the Clojure REPL:

  ```bash theme={null}
  clj
  ```

  On Java 24 or 25 you must pass the native-access flag:

  ```bash theme={null}
  clj -J--enable-native-access=ALL-UNNAMED
  ```

  Setting `JAVA_TOOL_OPTIONS` in your shell profile is the most convenient approach if you use Java 24+ regularly:

  ```bash theme={null}
  export JAVA_TOOL_OPTIONS="--enable-native-access=ALL-UNNAMED"
  clj
  ```

  ### Select a backend

  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.

  You can override automatic detection with environment variables:

  | Variable | Effect |
  | - | - |
  | *(unset)* | Automatic: CUDA if available, otherwise CPU |
  | `CLORCH_FORCE_CPU=1` | Forces the CPU backend regardless of hardware |
  | `CLORCH_FORCE_GPU=1` | Requests the CUDA backend; still requires compatible libraries and an NVIDIA driver |

  ### Install GPU system packages (CUDA only)

  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.

  Use a JDK, not a JRE. On Ubuntu with NVIDIA's CUDA package repository configured:

  ```bash theme={null}
  sudo apt-get update
  sudo apt-get install cuda-libraries-13-1 libcudnn9-cuda-13 libnccl2
  ```

  Confirm that the host exposes each GPU before starting Clojure:

  ```bash theme={null}
  nvidia-smi -L
  java -version
  clojure -Sdescribe
  ```

  ### Set environment variables and start the GPU REPL

  Set native-loading variables before the JVM starts. `JAVA_TOOL_OPTIONS` is inherited by launcher-created worker JVMs, which is important for distributed training:

  ```bash theme={null}
  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
  ```

  ### Verify CUDA from the REPL

  Once the REPL is running, confirm that CUDA is visible:

  ```clojure theme={null}
  (require '[clorch.cuda :as cuda]
           '[clorch.torch :as t])

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

## 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:

```text theme={null}
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](https://antlobach.github.io/clorch/docs/distributed) 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:

```bash theme={null}
clj -M:dev
```

The nREPL server listens on `127.0.0.1:7891` by default. Override the port or bind address with environment variables:

| Variable | Default | Effect |
| - | - | - |
| `CLORCH_NREPL_PORT` | `7891` | Port the nREPL server binds to |
| `CLORCH_NREPL_BIND` | `127.0.0.1` | Interface address the server listens on |

<Tip>
  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.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.