# Install bunqueue: Server and Clients for Your Runtime

Install the free bunqueue server and the client for Node.js, Deno, Python, PHP, Go, Rust, Elixir or Bun. Bun is required by the engine; network clients use their own runtime.

Canonical: https://bunqueue.dev/guide/installation/

---

import { Tabs, TabItem } from '@astrojs/starlight/components';

<div class="bq-wrap bq-hero">
  <span class="bq-eyebrow">guide · installation</span>
  <h1 class="bq-hero-h1 bq-bench-h1">Install for <em>your runtime.</em></h1>
  <p class="bq-hero-sub">The free bunqueue server runs on Bun. Your application uses the client for its own language. Bun applications can also embed the queue directly. The server, clients and queue features are included under MIT.</p>
</div>

## Requirements

- The `bunqueue` server and embedded runtime require [Bun](https://bun.sh)
  v1.4.0 or later when run from the package. Standalone executables and Docker
  images already include the runtime.
- External Node.js, Deno, Python, PHP, Go, Rust, and Elixir clients need their
  SDK's documented runtime plus a reachable Bun-powered bunqueue server; they
  do not require Bun in the client process.

## Install

<Tabs syncKey="lang">
<TabItem label="Bun">

```bash
bun add bunqueue
```

That is it. The package includes the client library, standalone server, and CLI. `msgpackr` is its only direct runtime dependency; SQLite, PostgreSQL connectivity, cron parsing, HTTP, WebSocket, and S3 use Bun's native APIs.

</TabItem>
<TabItem label="Node.js / Deno">

```bash
npm install bunqueue-client    # Node.js 20+
deno add npm:bunqueue-client   # Deno 2+
```

</TabItem>
<TabItem label="Python">

```bash
pip install bunqueue-client
```

</TabItem>
<TabItem label="PHP">

```bash
composer require bunqueue/client
```

</TabItem>
<TabItem label="Go">

```bash
go get github.com/egeominotti/bunqueue/sdk/go
```

</TabItem>
<TabItem label="Rust">

```bash
cargo add bunqueue-client
```

</TabItem>
<TabItem label="Elixir">

```elixir
# Hex release upcoming; use sdk/elixir as a path dependency today
{:bunqueue_client, path: "../bunqueue/sdk/elixir"}
```

</TabItem>
</Tabs>

_The Bun `bunqueue` package bundles the client, the server, and the CLI. Every other SDK is a client only: it connects to a bunqueue server, started once with `bunx bunqueue start` (see [SDKs](/guide/sdks/) and [Server Mode](/guide/server/))._

## Verify it works

<Tabs syncKey="lang">
<TabItem label="Bun">

Save this as `test.ts` and run `bun run test.ts`:

```typescript
import { Queue, Worker } from 'bunqueue/client';

// Both Queue and Worker must have embedded: true
const queue = new Queue('test', { embedded: true });
const worker = new Worker(
  'test',
  async (job) => {
    console.log('Processing:', job.data);
    return { success: true };
  },
  { embedded: true }
);

await queue.add('hello', { message: 'bunqueue is working!' });
```

</TabItem>
<TabItem label="Node.js / Deno">

Start a server (`bunx bunqueue start`), save this as `test.ts`, then run
`node --experimental-strip-types test.ts` (Node 22+) or `deno run -A test.ts`:



```typescript
import { Queue, Worker } from 'bunqueue-client';

// Both Queue and Worker must have embedded: false
const queue = new Queue('test', { embedded: false });
const worker = new Worker(
  'test',
  async (job) => {
    console.log('Processing:', job.data);
    return { success: true };
  },
  { embedded: false }
);

await queue.add('hello', { message: 'bunqueue is working!' });
```

</TabItem>
<TabItem label="Python">

Start a server (`bunx bunqueue start`), then run `python test.py`:

```python
from bunqueue import Queue, Worker

queue = Queue("test")  # connects to localhost:6789
queue.add("hello", {"message": "bunqueue is working!"})

def process(job):
    print("Processing:", job.data)
    return {"success": True}

Worker("test", process).run()
```

</TabItem>
<TabItem label="PHP">

Start a server (`bunx bunqueue start`), then run `php test.php`:

```php
use Bunqueue\Queue;
use Bunqueue\Worker;

$queue = new Queue('test'); // connects to localhost:6789
$queue->add('hello', ['message' => 'bunqueue is working!']);

$worker = new Worker('test', function (Bunqueue\Job $job) {
    var_dump($job->data());
    return ['success' => true];
});
$worker->run();
```

</TabItem>
<TabItem label="Go">

Start a server (`bunx bunqueue start`), then `go run .`:

```go
queue := bunqueue.NewQueue("test", bunqueue.Options{}) // localhost:6789
defer queue.Close()
queue.Add("hello", map[string]any{"message": "bunqueue is working!"}, nil)

worker := bunqueue.NewWorker("test", func(job *bunqueue.Job) (any, error) {
    fmt.Println("Processing:", job.Data())
    return map[string]any{"success": true}, nil
}, bunqueue.WorkerOptions{})
worker.Run()
```

</TabItem>
<TabItem label="Rust">

Start a server (`bunx bunqueue start`), then `cargo run`:

```rust
use bunqueue_client::{ConnectionOptions, JobOptions, Queue, Value, Worker, WorkerOptions};

let queue = Queue::new("test", ConnectionOptions::default()); // localhost:6789
let data = Value::Map(vec![(Value::from("message"), Value::from("bunqueue is working!"))]);
queue.add("hello", data, JobOptions::default())?;

let worker = Worker::new("test", |job| {
    println!("Processing: {:?}", job.data());
    Ok(Value::from(true))
}, WorkerOptions::default());
worker.run()?;
```

</TabItem>
<TabItem label="Elixir">

Start a server (`bunx bunqueue start`), then `mix run test.exs`:

```elixir
queue = Bunqueue.queue("test")  # connects to localhost:6789
{:ok, _job} = Bunqueue.Queue.add(queue, "hello", %{message: "bunqueue is working!"})

worker =
  Bunqueue.Worker.new("test", fn job ->
    IO.inspect(job.data, label: "Processing")
    {:ok, %{success: true}}
  end)

Bunqueue.Worker.run(worker)
```

</TabItem>
</Tabs>

You should see `Processing: { message: "bunqueue is working!" }`. Next: the [Quick Start](/guide/quickstart/) builds on this.

To check the server and CLI:

```bash
bunqueue --version
bunqueue start
```

## Docker (runtime included)

From 2.9.5, release images are available on Docker Hub as `egeominotti/bunqueue`
and on GHCR as `ghcr.io/egeominotti/bunqueue`. Both provide Linux amd64 and arm64
images under the same tag; Docker selects the appropriate architecture.

```bash
docker run -d --name bunqueue \
  -p 6789:6789 -p 6790:6790 \
  -v bunqueue-data:/app/data \
  egeominotti/bunqueue:2.9.5

curl http://localhost:6790/health
```

The named volume persists SQLite data at `/app/data`. TCP clients connect to port
6789; HTTP endpoints use port 6790. Use a version tag or digest for deployments;
`latest` follows the most recently published release.

## Single binary (no Bun required)

Each release ships self-contained executables, useful on servers and edge devices (Raspberry Pi, ARM64 boxes) where you don't want to install a runtime:

Starting with 2.9.5, choose one of eight archives from
[GitHub releases](https://github.com/egeominotti/bunqueue/releases):

| Operating system | Architecture | Archive |
|---|---|---|
| Linux (glibc) | x64 | `bunqueue-linux-x64.tar.gz` |
| Linux (glibc) | arm64 | `bunqueue-linux-arm64.tar.gz` |
| Linux (musl / Alpine) | x64 | `bunqueue-linux-x64-musl.tar.gz` |
| Linux (musl / Alpine) | arm64 | `bunqueue-linux-arm64-musl.tar.gz` |
| macOS | x64 / Intel | `bunqueue-darwin-x64.tar.gz` |
| macOS | arm64 / Apple Silicon | `bunqueue-darwin-arm64.tar.gz` |
| Windows | x64 | `bunqueue-windows-x64.zip` |
| Windows | arm64 | `bunqueue-windows-arm64.zip` |

For example, on Linux arm64 with glibc:

```bash
curl -fsSLO https://github.com/egeominotti/bunqueue/releases/latest/download/bunqueue-linux-arm64.tar.gz
tar -xzf bunqueue-linux-arm64.tar.gz
sudo mv bunqueue-linux-arm64 /usr/local/bin/bunqueue

bunqueue start --data-path /var/lib/bunqueue/queue.db
```

A `SHA256SUMS` file is attached to every release for checksum verification.
Download it from the same release as your archive. On Windows, extract the ZIP
and run `bunqueue-windows-x64.exe` or `bunqueue-windows-arm64.exe`.

The binary is the full server + CLI. For the client SDK in your app code you still install the package (`bun add bunqueue`).

## Install from source

```bash
git clone https://github.com/egeominotti/bunqueue.git
cd bunqueue
bun install
bun run build
```

## TypeScript support

bunqueue is written in TypeScript and ships full type definitions:

```typescript
import type {
  Job,
  JobOptions,
  WorkerOptions,
  StallConfig,
  DlqConfig,
  DlqEntry,
} from 'bunqueue/client';
```

:::tip[Next Steps]

- [Quick Start](/guide/quickstart/), build your first queue
- [Introduction](/guide/introduction/), what bunqueue is and when to use it
- [MCP Server](/guide/mcp/), let AI agents manage your queues
  :::