> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varianz.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Varianz v0.2.1 SDK and test packages for Python, TypeScript, Go, Java, and Kotlin from pkgs.varianz.io.

All Varianz packages are served from `pkgs.varianz.io`. It proxies only the `varianz` packages — your other dependencies keep resolving from PyPI, npm, or Maven Central as usual, and no credentials are required.

All ecosystems share the release version: **0.2.1** (`v0.2.1` for the Go module and Docker tags).

## Python

```bash theme={null}
pip install "varianz==0.2.1" "varianz-pytest==0.2.1" \
  --extra-index-url https://pkgs.varianz.io/python/simple/
```

To make the index permanent, put it in `requirements.txt`:

```ini theme={null}
--extra-index-url https://pkgs.varianz.io/python/simple/
varianz==0.2.1
varianz-pytest==0.2.1
```

**Packages:** `varianz` (runtime, includes the `varianz-scan` CLI) and `varianz-pytest` (pytest plugin — install only where you run tests).

<Warning>
  Use `--extra-index-url`, not `--index-url`. `--index-url` *replaces* PyPI, so every other dependency in the same command stops resolving. Keep the version pinned: placeholder packages named `varianz` and `varianz-pytest` exist on public PyPI (they hold the names and contain no SDK), and a pin guarantees you get the real package.
</Warning>

**Platforms:** wheels only (no sdist) for CPython 3.10–3.15 and PyPy 3.11 on macOS (x86\_64, arm64) and Linux glibc/musl (x86\_64, aarch64). Unsupported platforms fail with "no matching distribution found" rather than attempting a source build.

**Docker:** wheels are platform-specific, so install inside the image (the Linux wheel) rather than copying a macOS install in. Alternatively, run tests from the host against the service in Docker — the service and the test process only need to reach the same registry.

## TypeScript

The Node.js SDK works from TypeScript or plain JavaScript. Point the `@varianz` scope at `pkgs.varianz.io`, then install normally:

```bash theme={null}
echo '@varianz:registry=https://pkgs.varianz.io/npm/' >> .npmrc

# Runtime (pulls @varianz/cel and @varianz/client with it)
npm install --save @varianz/node@0.2.1

# Test integrations — install whichever you use
npm install --save-dev \
  @varianz/vitest@0.2.1 \
  @varianz/playwright@0.2.1 \
  @varianz/scanner@0.2.1
```

<Warning>
  Scope the registry; do not use `--registry`. The `--registry` flag redirects *every* lookup, so npm asks `pkgs.varianz.io` for public transitive dependencies and gets a 404. The `@varianz:registry=` line sends only `@varianz/*` there.
</Warning>

The matching native binary for your OS/CPU/libc is included in each tarball — no build tools, no postinstall step.

**Platforms:** Node.js 22+ on macOS (arm64, x64) and Linux glibc/musl (x64, arm64). The `using`-based automatic stage cleanup requires Node 23+.

**TypeScript config:** the decorator API uses TC39 (stage-3) decorators — TypeScript ≥ 5.0 with `experimentalDecorators` left at its default (`false`).

## Go

```bash theme={null}
go get go.varianz.io/sdk@v0.2.1
```

The module resolves like any other Go dependency. Native libraries are pre-built and bundled inside the module; platform-specific `#cgo` directives link the correct one automatically. `go mod vendor` works normally.

**CGo is required.** The SDK links a Rust native library, so build with `CGO_ENABLED=1`. In Docker, that rules out the common `CGO_ENABLED=0` + `distroless/static` pattern:

```dockerfile theme={null}
# Builder: needs gcc + glibc headers for CGo
FROM golang:1.22-bookworm AS builder
ENV CGO_ENABLED=1
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o /service ./cmd/service

# Runtime: needs glibc, not build tools
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /service /service
ENTRYPOINT ["/service"]
```

The runtime image can be `debian:bookworm-slim` or `gcr.io/distroless/base-debian12`; `distroless/static` and `scratch` will not work. Don't force `--platform=$BUILDPLATFORM` in the builder stage — CGo must compile for the runtime platform.

<Note>
  If checksum verification fails for this module in your environment (for example, behind a proxy that blocks `proxy.golang.org`), set `GONOSUMDB='go.varianz.io/*'` or use `GOPRIVATE=go.varianz.io/*`.
</Note>

## Java

The Gradle plugin adds the SDK modules, configures the annotation processor, and attaches the `varianz-agent` to `Test` and `JavaExec` tasks automatically.

```kotlin theme={null}
// settings.gradle.kts
pluginManagement {
    repositories {
        maven { url = uri("https://pkgs.varianz.io/maven") }
        gradlePluginPortal()
    }
}
```

```kotlin theme={null}
// build.gradle.kts
plugins {
    id("io.varianz.sdk") version "0.2.1"
}

repositories {
    mavenCentral()   // keep it — processor deps (JavaParser, ByteBuddy) resolve here
    maven { url = uri("https://pkgs.varianz.io/maven") }
}

varianz {
    sdkVersion.set("0.2.1")
}
```

**Plugin options:**

| Property        | Default | Description                                                                                            |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `sdkVersion`    | —       | SDK version resolved from your repositories. Mutually exclusive with `sdkDir`; exactly one must be set |
| `sdkDir`        | —       | A local directory of SDK JARs instead of a repository (air-gapped builds)                              |
| `includeJunit`  | `true`  | Add `io.varianz:varianz-junit` to `testImplementation`                                                 |
| `weave`         | `true`  | Attach the `varianz-agent` to `Test`/`JavaExec` tasks. `false` = `@VPoint` methods run uninstrumented  |
| `failOnWarning` | `false` | Treat annotation-processor warnings as errors                                                          |

If your project uses protobuf/gRPC, also add those to `annotationProcessor` so the processor can resolve proto types in `@VPoint` signatures.

<Warning>
  **Production launchers need the agent too.** The plugin attaches `-javaagent:` only to Gradle `Test` and `JavaExec` tasks. A deployed service started from an `installDist` script or `java -jar` runs *without* the agent — `@VPoint` methods execute their original bodies and stages never fire. Add `-javaagent:varianz-agent-0.2.1-agent.jar` (and, on Java 22+, `--enable-native-access=io.varianz.native_loader`) to the production launch command. See [Java SDK](/sdks/java#how-interception-works) for details.
</Warning>

**Maven** users: see the [Java SDK page](/sdks/java#maven) for the full `pom.xml` setup (BOM import, `varianz-starter`, `java-processor` with the `all` classifier, and the `varianz-maven-plugin` `prepare-agent` goal).

**Docker:** both glibc images (`eclipse-temurin:21-jdk`) and Alpine (`eclipse-temurin:21-jdk-alpine`) work — the JARs bundle glibc and musl native libraries.

## Kotlin

Kotlin uses its own KSP-based plugin, `io.varianz.sdk.kotlin` (not the Java plugin). Four things trip up first-time setup:

```kotlin theme={null}
plugins {
    id("com.google.devtools.ksp") version "2.1.10-1.0.29" // 1. KSP must come first
    id("io.varianz.sdk.kotlin")                           // 2. Kotlin-specific plugin id
}

dependencies {
    ksp("com.github.javaparser:javaparser-core:3.27.0")   // 3. plugin does not add this
}

// 4. Configure via the typed extension
configure<io.varianz.gradle.kotlin.VarianzKotlinExtension> {
    sdkVersion.set("0.2.1")
}
```

The `pluginManagement` repository block is the same as for Java. Annotation attributes need named arguments in Kotlin: `@VPoint(name = "…")`, not positional.

## After installing

Every SDK is **disabled by default** — set `VARIANZ_ENABLED=true` and point it at a registry to activate it. (Java/Kotlin additionally need the `varianz-agent` attached, which the build plugins handle for test and run tasks.) Local plaintext registries additionally need `VARIANZ_INSECURE_ALLOW_PLAINTEXT=true` on every connecting process. See [Configuration](/reference/configuration) for the full environment-variable reference, and the [Quickstart](/quickstart) to verify your install end to end.