# System Requirements for Running Convert Conversions Locally

> Discover the system requirements for running Convert locally. You need Bun 1.0+, Git with submodule support, and a modern WebAssembly browser for all conversion engines.

- Repository: [p2r3/convert](https://github.com/p2r3/convert)
- Tags: system-requirements
- Published: 2026-02-19

---

**You need Bun ≥ 1.0, Git with submodule support, and a modern WebAssembly-capable browser to run Convert locally; all conversion engines are WebAssembly-based, so no native codecs or system binaries are required.**

The **p2r3/convert** repository is a pure-web, client-side file conversion suite that performs all processing in the browser using WebAssembly. Understanding the system requirements for running Convert conversions locally ensures you can deploy the development server and WASM engines correctly without installing heavy native dependencies.

## Core System Requirements

### Bun JavaScript Runtime (≥ 1.0)

Convert requires **Bun** as its JavaScript runtime and package manager. According to [README lines 44-48](https://github.com/p2r3/convert/blob/master/README.md#L44-L48), Bun handles dependency installation via `bun install` and runs the Vite development server using `bunx vite`. Install Bun from [bun.sh](https://bun.sh/) before proceeding.

### Git with Submodule Support

The repository pulls in external format-handler submodules that are essential for conversion functionality. As noted in [README line 45](https://github.com/p2r3/convert/blob/master/README.md#L45), you must clone recursively using `git clone --recursive` or run `git submodule update --init --recursive` after a standard clone.

### WebAssembly-Capable Browser

All conversions execute client-side using WebAssembly (WASM) engines. You need a modern browser that supports WebAssembly, including recent versions of **Chrome**, **Edge**, **Firefox**, or **Safari**. The WASM assets are served from `/convert/wasm/` and dynamically loaded by handlers such as [[`src/handlers/FFmpeg.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/FFmpeg.ts)](https://github.com/p2r3/convert/blob/master/src/handlers/FFmpeg.ts#L15-L36). No browser plugins or external codecs are necessary.

## Step-by-Step Local Installation

Follow these commands to set up Convert on your local machine:

1. Clone the repository with submodules:

```bash
git clone --recursive https://github.com/p2r3/convert
cd convert

```

2. Install JavaScript dependencies:

```bash
bun install

```

3. Start the development server:

```bash
bunx vite

```

The dev server opens on `http://localhost:5173` by default. Navigate to this URL in your browser, drag a file onto the interface, select an output format, and click **Convert**. The conversion executes entirely in your browser using the WASM engines defined in [[`src/handlers/FFmpeg.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/FFmpeg.ts)](https://github.com/p2r3/convert/blob/master/src/handlers/FFmpeg.ts), [[`src/handlers/ImageMagick.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/ImageMagick.ts)](https://github.com/p2r3/convert/blob/master/src/handlers/ImageMagick.ts), and [[`src/handlers/sqlite.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/sqlite.ts)](https://github.com/p2r3/convert/blob/master/src/handlers/sqlite.ts).

## Optional Requirements for Cache Generation

While not required for basic operation, pre-generating the format-list cache requires **Chromium** or headless Chrome. The [[`buildCache.js`](https://github.com/p2r3/convert/blob/main/buildCache.js)](https://github.com/p2r3/convert/blob/master/package.json#L16) script uses Puppeteer—listed in `devDependencies` in [[`package.json`](https://github.com/p2r3/convert/blob/main/package.json)](https://github.com/p2r3/convert/blob/master/package.json#L16)—to generate the cache. Puppeteer downloads a compatible Chromium binary automatically, but your host OS must support running it (Linux glibc, macOS, or Windows).

Alternatively, generate the cache manually by starting the dev server, opening the browser console (F12), and running:

```javascript
printSupportedFormatCache()  // Returns JSON string

```

Save the output to [`cache.json`](https://github.com/p2r3/convert/blob/main/cache.json) in the project root to speed up subsequent startups.

## Docker Deployment Alternative

If you prefer not to install Bun locally, Convert provides a containerized environment. As detailed in [README lines 56-66](https://github.com/p2r3/convert/blob/master/README.md#L56-L66), the Debian-based Docker image includes Chromium, FFmpeg-WASM, ImageMagick-WASM, and all necessary dependencies.

Run the container using Docker Compose:

```bash
docker compose -f docker/docker-compose.yml up -d

```

The service becomes available at `http://localhost:8080/convert/`. This approach requires only Docker and a browser—no local Bun installation or native binaries.

## WebAssembly Architecture and Native Code

Convert eliminates the need for system-level codecs through WASM modules. The entry point in [[`src/main.ts`](https://github.com/p2r3/convert/blob/main/src/main.ts)](https://github.com/p2r3/convert/blob/master/src/main.ts) initializes the UI and conversion graph, while [[`vite.config.js`](https://github.com/p2r3/convert/blob/main/vite.config.js)](https://github.com/p2r3/convert/blob/master/vite.config.js) configures static asset locations.

You can interact with these WASM engines programmatically. For example, converting audio using the FFmpeg handler directly requires only the browser—no native `ffmpeg` binary:

```typescript
import { FFmpeg } from "@ffmpeg/ffmpeg";

async function wavFromMp3(mp3Bytes: Uint8Array): Promise<Uint8Array> {
  const ffmpeg = new FFmpeg();
  await ffmpeg.load({ coreURL: "/convert/wasm/ffmpeg-core.js" });
  await ffmpeg.writeFile("in.mp3", mp3Bytes);
  await ffmpeg.exec(["-i", "in.mp3", "-f", "wav", "out.wav"]);
  const wav = await ffmpeg.readFile("out.wav");
  await ffmpeg.terminate();
  return new Uint8Array(wav);
}

```

This function works in any WebAssembly-capable browser, loading the core from [`/convert/wasm/ffmpeg-core.js`](https://github.com/p2r3/convert/blob/main//convert/wasm/ffmpeg-core.js) as referenced in [[`src/handlers/FFmpeg.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/FFmpeg.ts)](https://github.com/p2r3/convert/blob/master/src/handlers/FFmpeg.ts#L15-L36).

## Summary

- **Bun ≥ 1.0** is mandatory for dependency management and running the Vite development server
- **Git with submodules** is required to fetch external format handlers documented in the repository
- **Modern browsers** with WebAssembly support handle all conversions; no native FFmpeg, ImageMagick, or SQLite binaries are needed
- **Chromium** is only required for the optional [`buildCache.js`](https://github.com/p2r3/convert/blob/main/buildCache.js) script that uses Puppeteer
- **Docker** offers a self-contained alternative that bundles all dependencies including the Debian-based image configuration

## Frequently Asked Questions

### Do I need to install FFmpeg or ImageMagick on my system?

No. Convert uses WebAssembly builds of FFmpeg and ImageMagick that execute entirely within the browser. As implemented in [[`src/handlers/FFmpeg.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/FFmpeg.ts)](https://github.com/p2r3/convert/blob/master/src/handlers/FFmpeg.ts#L15-L36), the application loads WASM assets from `/convert/wasm/` and performs conversions client-side without accessing native system binaries.

### Can I run Convert on Windows, macOS, and Linux?

Yes. Convert supports any operating system capable of running Bun and a modern web browser. The optional Docker deployment works cross-platform, and the WebAssembly engines execute identically across all supported browsers regardless of the host operating system.

### Is Bun strictly required, or can I use Node.js?

The project is specifically configured for Bun. The [README](https://github.com/p2r3/convert/blob/master/README.md#L44-L48) explicitly documents `bun install` and `bunx vite` as the standard commands for serving assets. While Node.js might function in some scenarios, Bun is the only officially supported runtime for local development.

### Does Convert require an internet connection to perform conversions?

No. Once the application and WASM binaries are cached by the browser, all conversions happen offline. The only online requirement is the initial load of the web application and WASM assets from the local development server or the initial Docker pull.