JVM installation

Install io.github.underloam:xbbg.

Maven and Gradle resolve io.github.underloam:xbbg and the optional io.github.underloam:xbbg-jdk17 add-on from Maven Central. The core jar bundles the JNI native libraries for Windows x64, Linux x64, and macOS arm64.

Requirements

Requirement	Details
JVM	Java 8 or newer for io.github.underloam:xbbg. Java 17 or newer for io.github.underloam:xbbg-jdk17 (Java 21+ for exhaustive pattern-matching switch and virtual threads).
Platform	Bundled JNI native libraries for Windows x64 (windows-x86_64), Linux x64 with glibc 2.28+ (linux-x86_64), and macOS arm64 (macos-aarch64).
Bloomberg	Access through the Desktop API (a Terminal session), B-PIPE, SAPI, or ZFP, plus the Bloomberg C++ SDK runtime library (blpapi3_64.dll on Windows, libblpapi3_64.so on Linux and macOS).

Install from Maven Central

Both artifacts are published to Maven Central. Add io.github.underloam:xbbg for the full API, and optionally io.github.underloam:xbbg-jdk17 when running on Java 17 or newer:

Maven (pom.xml)

<dependencies>
  <dependency>
    <groupId>io.github.underloam</groupId>
    <artifactId>xbbg</artifactId>
    <version>1.8.1</version>
  </dependency>

  <!-- Optional: Flow publishers, sealed types, Arrow Java interop, virtual threads (Java 17+) -->
  <dependency>
    <groupId>io.github.underloam</groupId>
    <artifactId>xbbg-jdk17</artifactId>
    <version>1.8.1</version>
  </dependency>
</dependencies>

Gradle Kotlin DSL (build.gradle.kts)

dependencies {
    implementation("io.github.underloam:xbbg:1.8.1")

    // Optional: Flow publishers, sealed types, Arrow Java interop, virtual threads (Java 17+)
    implementation("io.github.underloam:xbbg-jdk17:1.8.1")
}

• Maven Central: io.github.underloam:xbbg · io.github.underloam:xbbg-jdk17
• Javadoc: javadoc.io/doc/io.github.underloam/xbbg

What gets installed

Artifact	Module name	Contents
io.github.underloam:xbbg	io.github.underloam.xbbg	The full Java 8+ API and bundled JNI native libraries (xbbg_jni for the engine and xbbg_sdk_jni for Bloomberg runtime provisioning) for Windows x64, Linux x64, and macOS arm64. Zero third-party runtime dependencies.
io.github.underloam:xbbg-jdk17	io.github.underloam.xbbg.jdk17	Java 17+ add-on (XbbgFlow, DeliveryView, TickValue, TickValues, Errors, ErrorKind, ArrowBackends, ArrowTables, VirtualThreads). Depends only on io.github.underloam:xbbg; Apache Arrow Java dependencies are optional.

Optional Apache Arrow Java dependencies

Every type in io.github.underloam:xbbg-jdk17 except ArrowBackends and ArrowTables works with no extra dependencies. If you use ArrowBackends.vectorSchemaRoot(allocator) or ArrowTables.toVectorSchemaRoot(table, allocator), add org.apache.arrow:arrow-vector and an Arrow memory allocator (arrow-memory-unsafe or arrow-memory-netty) to your project:

Maven (pom.xml)

<dependency>
  <groupId>org.apache.arrow</groupId>
  <artifactId>arrow-vector</artifactId>
  <version>18.3.0</version>
</dependency>
<dependency>
  <groupId>org.apache.arrow</groupId>
  <artifactId>arrow-memory-unsafe</artifactId>
  <version>18.3.0</version>
</dependency>

Gradle Kotlin DSL (build.gradle.kts)

dependencies {
    implementation("org.apache.arrow:arrow-vector:18.3.0")
    implementation("org.apache.arrow:arrow-memory-unsafe:18.3.0")
}

JVM flags for JDK 24+ and Arrow Java

• Native access on JDK 24+. On JDK 24 and newer (JEP 472), start the JVM with --enable-native-access=ALL-UNNAMED on the class path, or --enable-native-access=io.github.underloam.xbbg on the module path, to avoid the restricted native-access warning. If the same launch arguments must also work on Java 8 or Java 11, prepend -XX:+IgnoreUnrecognizedVMOptions:

java -XX:+IgnoreUnrecognizedVMOptions --enable-native-access=ALL-UNNAMED -cp ...

The Enable-Native-Access: ALL-UNNAMED attribute in xbbg's jar manifest is honored by the JDK only when xbbg is packaged inside an executable uber-jar started with java -jar.

• Arrow Java on JDK 17+. When using ArrowBackends or ArrowTables with Apache Arrow Java, pass --add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED so Arrow's memory layer can access direct NIO buffer addresses. With arrow-memory-netty, also pass -Dio.netty.tryReflectionSetAccessible=true. On JDK 24+, --sun-misc-unsafe-memory-access=allow silences the JEP 498 sun.misc.Unsafe warning from Arrow's memory allocator.

Bloomberg C++ SDK runtime discovery

xbbg loads the Bloomberg C++ SDK runtime library (blpapi3_64.dll on Windows, libblpapi3_64.so or libblpapi3.so on Linux, and libblpapi3_64.so, libblpapi3.so, or libblpapi3.dylib on macOS) before loading its own xbbg_jni engine library. xbbg never bundles Bloomberg's library.

On the first call that needs the native engine, xbbg searches the following locations in order and uses the first match:

1. Explicit path: Xbbg.setSdkPath(Path) (called before the natives load) or the -Dxbbg.blpapi.path=<file or directory> system property. A directory is also searched as an SDK root (bin, lib, Lib, lib/win64, lib/win32, Linux, Darwin, and versioned subdirectories). If an explicit path is set and holds no runtime library, loading fails immediately with BlpapiNotFoundException.
2. SDK environment variables: BLPAPI_LIB_DIR (a directory holding the library), then BLPAPI_ROOT and XBBG_DEV_SDK_ROOT (searched as SDK roots, including versioned children newest-first).
3. Bloomberg Terminal (DAPI) and system path: On Windows, standard DAPI directories (%SystemDrive%\blp\DAPI, %ProgramFiles%\Bloomberg\Blp\DAPI, %ProgramFiles(x86)%\Bloomberg\Blp\DAPI, %LOCALAPPDATA%\Bloomberg\DAPI, %LOCALAPPDATA%\Bloomberg\Blp\DAPI), then each entry on the Windows PATH. On Linux and macOS, ~/blp/DAPI and /opt/bloomberg/DAPI.
4. Provisioned cache: The newest valid runtime previously installed into <cache>/sdk/<version>/<platform>/ whose library file matches the SHA-256 recorded in its provenance.json. The cache root defaults to -Dxbbg.cache.dir, XBBG_CACHE_DIR, or the platform cache directory (%LOCALAPPDATA%\xbbg on Windows, $HOME/Library/Caches/xbbg on macOS, $XDG_CACHE_HOME/xbbg or $HOME/.cache/xbbg on Linux).
5. Automatic provisioning from a configured source: When no local or cached runtime is found and a source is configured via Xbbg.setSdkSource(BlpapiSource), -Dxbbg.sdk.source, or XBBG_SDK_SOURCE (with an optional version in -Dxbbg.sdk.version or XBBG_SDK_VERSION), xbbg downloads, hash-verifies, and atomically installs the runtime into its cache.

Pointing at an existing SDK directory

import io.github.underloam.xbbg.Xbbg;
import java.nio.file.Paths;

public class ConfigureSdkPath {
  public static void main(String[] args) {
    // Must be called before the native library is loaded
    Xbbg.setSdkPath(Paths.get("/opt/bloomberg/blpapi_cpp_3.26.9.1"));
    System.out.println("Loaded BLPAPI runtime: " + Xbbg.sdkVersion());
  }
}

Provisioning the runtime from PyPI, conda, or an artifact

When running on a server, container, or CI machine without a local Terminal install, configure a BlpapiSource from Bloomberg's Python wheel index, conda-forge, a corporate mirror, or a local/remote package file (.whl, .conda, .tar.bz2):

import io.github.underloam.xbbg.Xbbg;
import io.github.underloam.xbbg.sdk.BlpapiSdk;
import io.github.underloam.xbbg.sdk.BlpapiSource;
import io.github.underloam.xbbg.sdk.ProvisionOptions;
import io.github.underloam.xbbg.sdk.ProvisionResult;
import java.nio.file.Paths;

public class ProvisionRuntime {
  public static void main(String[] args) {
    // Option 1: Lazy provisioning on first engine use
    Xbbg.setSdkSource(BlpapiSource.pypi(BlpapiSource.BLOOMBERG_PYPI_INDEX));
    // Or: BlpapiSource.conda("https://conda.anaconda.org/conda-forge")
    // Or: BlpapiSource.artifact("https://mirror.example.com/blpapi-3.26.9.1-py3-none-win_amd64.whl#sha256=...")

    // Option 2: Explicit programmatic provisioning with full options
    ProvisionResult result =
        Xbbg.await(
            BlpapiSdk.provision(
                ProvisionOptions.builder()
                    .source(BlpapiSource.conda("conda-forge"))
                    .version("3.26.9.1")
                    .cacheDir(Paths.get("/opt/xbbg-cache"))
                    .build()));
    System.out.println("Provisioned " + result.version() + " at " + result.libraryPath());
  }
}

You can also pre-populate the cache during a Docker build or server image bake using the built-in CLI entry point (which uses xbbg_sdk_jni and does not require blpapi to be present yet):

java -cp xbbg-1.8.1.jar io.github.underloam.xbbg.sdk.BlpapiSdk \
    --source conda:https://conda.anaconda.org/conda-forge \
    --cache-dir /opt/xbbg-cache

Wheels older than 3.24.10 are refused because earlier wheels rename the shared library. Bloomberg's license terms apply to the runtime library however it is obtained.

Verify the installation

import io.github.underloam.xbbg.Xbbg;

public class VerifyInstall {
  public static void main(String[] args) {
    System.out.println("xbbg jar version:    " + Xbbg.version());
    System.out.println("xbbg native version: " + Xbbg.nativeVersion());
    System.out.println("blpapi SDK version:  " + Xbbg.sdkVersion());
  }
}

Xbbg.version() reads the jar's build stamp without loading native code. Xbbg.nativeVersion() and Xbbg.sdkVersion() extract and load the bundled JNI library and the Bloomberg runtime library without opening a Bloomberg session.

Next steps

Quickstart

Make your first reference, historical, bulk, intraday, BQL, and streaming calls.

Configuration

Configure B-PIPE, SAPI, failover servers, TLS, ZFP, SOCKS5, and worker pools.

Output Formats

Work with Table, Column, RowsResult, and Apache Arrow Java vectors.

API Surface

Browse every public class and method in xbbg and xbbg-jdk17.