# ol.vips

> Clojure bindings for [libvips](https://github.com/libvips/libvips) image
> processing library

![doc](https://img.shields.io/badge/doc-outskirtslabs-orange.svg)
![status: experimental](https://img.shields.io/badge/status-experimental-orange.svg)
![alt=nixbot](https://ci.outskirtslabs.com/repos/github/outskirtslabs/vips/badge.svg)

`ol.vips` is a Clojure library for loading, transforming, and saving
images with [libvips](https://github.com/libvips/libvips). Use it to
build thumbnails and responsive image variants, convert formats, crop
and resize uploads, compose images, read and write metadata, and run
image pipelines from files, byte arrays, or streams.

If you have never used libvips before: it is a native image processing
library designed for fast, memory-efficient image work. `ol.vips` gives
Clojure programs access to that engine with a Clojure-first API,
generated wrappers for the full libvips operation surface, and
platform-native jars so you can use libvips from the JVM without
building the native integration yourself.

`ol.vips` requires Java 25{plus} or GraalVM Native Image 25{plus}.

Project status: **[Experimental](https://docs.outskirtslabs.com/open-source-vital-signs#experimental)**.

It is used in production, but needs more exercise and feedback from the community before I commit to a stable version.

## Installation

Install the main library plus exactly one native jar that matches your
target platform.

```clojure
;; deps.edn
{:deps {com.outskirtslabs/vips {:mvn/version "0.1.0"}
        ;; change the following based on your runtime platform
        com.outskirtslabs/vips-native-linux-x86-64-gnu {:mvn/version "1.3.3-1"}}}
```

https://clojars.org/search?q=group-id%3Acom.outskirtslabs+AND+artifact-id%3Avips-native*[Choose
one or more native artifacts] (only the appropriate one for the runtime
platform will be used):

* `com.outskirtslabs/vips-native-linux-x86-64-gnu`
* `com.outskirtslabs/vips-native-linux-x86-64-musl`
* `com.outskirtslabs/vips-native-linux-aarch64-gnu`
* `com.outskirtslabs/vips-native-linux-aarch64-musl`
* `com.outskirtslabs/vips-native-macos-x86-64`
* `com.outskirtslabs/vips-native-macos-aarch64`
* `com.outskirtslabs/vips-native-win32-x86-64`

The native companion jars bundle libvips 8.18.6 from `sharp-libvips` 1.3.3.
The test suite runs against that bundle.

`ol.vips` requires Java 25{plus} and native access enabled for the JVM
process:

```clojure
;; deps.edn
{:aliases
 {:dev {:jvm-opts ["--enable-native-access=ALL-UNNAMED"]}}}
```

To use your own libvips build, see
[Loading the native library](https://docs.outskirtslabs.com/ol.vips/next/introduction#loading_the_native_library).

## Quick Start

```clojure
(require '[ol.vips :as v]
         '[ol.vips.operations :as ops])

(v/init!)

(with-open [thumb   (ops/thumbnail "dev/rabbit.jpg" 300 {:auto-rotate true})
            rotated (ops/rotate thumb 90.0)]
  (v/write-to-file rotated "thumbnail.jpg")
  (v/metadata rotated))
;; => {:width 300, :height 242, :bands 3, :has-alpha? false}
```

The top-level `ol.vips` namespace provides the image loading, saving,
metadata, and convenience helpers. `ol.vips.operations` contains
generated wrappers for libvips operations.

## Documentation

* [Docs Home](https://docs.outskirtslabs.com/ol.vips/next/)
* [Introduction](https://docs.outskirtslabs.com/ol.vips/next/introduction/)
* [Examples](https://docs.outskirtslabs.com/ol.vips/next/examples/)
* [Going to Production](https://docs.outskirtslabs.com/ol.vips/next/going-to-production/)
* [GraalVM Native Image](https://docs.outskirtslabs.com/ol.vips/next/native-image/)
* [Multipage and Animated Images](https://docs.outskirtslabs.com/ol.vips/next/multipage-and-animated-images/)
* [API Reference](https://docs.outskirtslabs.com/ol.vips/next/api/ol-vips)
* [Changelog](https://docs.outskirtslabs.com/ol.vips/next/changelog/)
* [Security Policy](https://docs.outskirtslabs.com/ol.vips/next/security/)
* [Support via GitHub Issues](https://github.com/outskirtslabs/vips/issues)

## Licensing

The Clojure library `ol.vips` is copyright (C) 2026 Casey Link and is
licensed under [EUPL-1.2](https://spdx.org/licenses/EUPL-1.2.html).

The platform-native companion jars under `native/` redistribute upstream
[sharp-libvips](https://github.com/lovell/sharp-libvips/releases) binary
bundles. Those redistributed native binaries are licensed separately
from the `ol.vips` source, principally under LGPL-3.0-or-later.