Skip to main content

​
Installation

Get started with bun-scikit in your Bun project.

​
Requirements

Bun 1.3.9 or later is required to run bun-scikit.
Check your Bun version: 
bun --version
If you need to install or upgrade Bun: 
curl -fsSL https://bun.sh/install | bash

​
Install bun-scikit

1

Add the package

Install bun-scikit using Bun’s package manager:
bun add bun-scikit
This installs the latest stable version from npm.
2

Verify installation

Create a test file test.ts to verify the installation:
import { LinearRegression } from "bun-scikit";

const model = new LinearRegression();
console.log("bun-scikit installed successfully!");
Run it:
bun run test.ts
3

Check Zig backend (optional)

Verify that native Zig acceleration is working for tree-based models:
import { DecisionTreeClassifier } from "bun-scikit";

const X = [
  [0, 0],
  [0, 1],
  [1, 0],
  [2, 2],
  [2, 3],
  [3, 2],
];
const y = [0, 0, 0, 1, 1, 1];

const tree = new DecisionTreeClassifier({ maxDepth: 3, randomState: 42 });
tree.fit(X, y);
console.log("DecisionTree backend:", tree.fitBackend_);
Expected output:
DecisionTree backend: zig
If you see fitBackend_: "zig", native acceleration is enabled and working.

​
Native Binaries

bun-scikit includes prebuilt native binaries for optimal performance:

Linux x64

Prebuilt binaries included

Windows x64

Prebuilt binaries included

macOS

Build from source (prebuilt binaries not yet available)

Other Platforms

JavaScript fallback available
No build step required - Prebuilt binaries work out of the box. No need to run bun pm trust or build from source.

​
Configuration (Advanced)

For advanced users, bun-scikit supports several environment variables to customize native acceleration:

​
Native Bridge Mode

export BUN_SCIKIT_NATIVE_BRIDGE=node-api  # or 'ffi'
  • node-api: Use Node-API bridge (default)
  • ffi: Use FFI bridge

​
Custom Binary Paths

# Custom Node addon path
export BUN_SCIKIT_NODE_ADDON=/path/to/bun_scikit_node_addon.node

# Custom Zig library path
export BUN_SCIKIT_ZIG_LIB=/path/to/bun_scikit_kernels.so

​
Tree Backend Selection

# Force JavaScript fallback for tree-based models
export BUN_SCIKIT_TREE_BACKEND=js

# Use Zig backend (default)
export BUN_SCIKIT_TREE_BACKEND=zig
The default zig backend provides significant performance improvements for DecisionTreeClassifier, DecisionTreeRegressor, RandomForestClassifier, and RandomForestRegressor.

​
TypeScript Configuration

bun-scikit is fully typed. If you’re using TypeScript, no additional configuration is needed: 
{
  "compilerOptions": {
    "types": ["bun-types"]
  }
}

​
Troubleshooting

Make sure you’re using Bun 1.3.9 or later:
bun --version
Clear your cache and reinstall:
rm -rf node_modules bun.lockb
bun install
This can happen if:
  1. You’re on an unsupported platform (macOS prebuilts not yet available)
  2. The native binaries failed to load
  3. You set BUN_SCIKIT_TREE_BACKEND=js
The JavaScript fallback still works correctly, just without native acceleration.
Ensure you have the latest Bun types:
bun add -d @types/bun
Run type checking:
bunx tsc --noEmit

​
Next Steps

Quick Start

Train your first model

API Reference

Explore the full API

Build docs developers (and LLMs) love

Get started for freeTalk to us