microsoft / microsoft/onnxruntime

[Feature Request] [Java] Configurable Native Library Extraction

Open
#27,656 19 comments 0 reactions 0 assignees View on GitHub
api:Java feature request
Dominant language
C++
Stars
21.9k
Forks
4.2k
Avg merge
4d 11h
Merged PRs (30d)
184

Description

### Describe the feature request

**Goal:** Provide developers with granular control over the extraction location and persistence of bundled native libraries to support restricted environments, dependency enrichment, and startup optimization.

#### **Proposed Configuration Properties**

| Property | Description |
| --- | --- |
| **`onnxruntime.native.extract.path`** | Specifies a custom directory for extracting native libraries from the JAR. If unset, the system uses the default temporary directory. |
| **`onnxruntime.native.extract.cleanup`** | Boolean (default: `true`). If `false`, the extraction directory and its contents are NOT marked for deletion on JVM exit. |

#### **Differentiation from `onnxruntime.native.path`:**
The existing `onnxruntime.native.path` property is used to point the loader to a directory of *externally provided* binaries. This new request focuses on cases where the user *wants* to use the libraries bundled in the JAR, but needs to control exactly where they are unpacked.

#### **Suggested Workflow Changes**

1. **Init Logic:** Check `onnxruntime.native.extract.path`. If set, use it as the base for `tempDirectory`.
2. **Smart Extraction:** If a custom path is used and a library already exists there (optionally verifying version/size), skip the extraction I/O.
3. **Conditional Cleanup:** Only register `file.deleteOnExit()` if `onnxruntime.native.extract.cleanup` is `true`.

### Describe scenario use case

* **Dependency Enrichment:**
By defining a predictable extraction path, users can "enrich" that directory before the runtime initializes. For example, a user could place required CUDA runtime libraries (not bundled in the JAR) into the custom extraction folder. Since the OS dynamic linker typically checks the directory of the loading library first, this ensures the ONNX Runtime CUDA provider finds its dependencies without complex system-wide `PATH`/`LD_LIBRARY_PATH` modifications.
* **Startup Performance & Persistence:**
Currently, every JVM launch forces a new extraction to a randomized temp folder followed by a `deleteOnExit()`. For frequently restarted applications (e.g., CLI tools, serverless functions, or rapid development cycles), this adds significant I/O overhead. Allowing users to disable cleanup and reuse a persistent directory enables a "cache" mechanism that dramatically speeds up subsequent initializations.

Contributor guide

Open the contributing guide

Research direction

Start by locating the Java native-library initialization and the existing handling for onnxruntime.native.path. Trace how bundled libraries are extracted, how tempDirectory is selected, and where deleteOnExit() is registered. Done means the two proposed properties control the extraction directory and cleanup behavior, with persistent reuse handled as specified.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
backend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.