# Run FerretDB on Windows (No Docker, No WSL)

> FerretDB v2 needs a PostgreSQL extension that is not on Windows yet. We built custom binaries to run FerretDB v1 natively on Windows, no Docker or WSL.

Published: 2026-07-17
Canonical: https://layerbase.com/blog/ferretdb-on-windows-without-docker

Short version: FerretDB v2 cannot run natively on Windows, because it depends on the `postgresql-documentdb` PostgreSQL extension, which is written in C against POSIX APIs and does not build there. The FerretDB proxy binary exists for Windows; the backend it needs does not. So we built custom binaries for FerretDB v1, which stores documents in plain PostgreSQL with no extension, and run it natively through Layerbase Desktop or the Layerbase CLI. No Docker, no WSL.

FerretDB gives you the MongoDB API backed by PostgreSQL. You write MongoDB queries using standard drivers and tools like `mongosh`, and FerretDB translates them into PostgreSQL operations. Your data lives in PostgreSQL tables with full ACID guarantees, but your application code looks like any other MongoDB project.

Running FerretDB on Windows is complicated. FerretDB v2 (the current version) depends on `postgresql-documentdb`, a PostgreSQL extension that handles document storage. That extension doesn't build on Windows. The FerretDB binary itself is available for Windows, but without the backend extension, it won't start.

We built custom binaries that let you run FerretDB v1 natively on Windows through [Layerbase Desktop](https://layerbase.com/desktop/download) or [the Layerbase CLI](https://layerbase.com/docs/cli) (formerly SpinDB). FerretDB v1 uses plain PostgreSQL for storage (no extension required), so it works on Windows without any Linux dependency.

## Contents

- [The Windows Problem: v1 vs v2](#the-windows-problem-v1-vs-v2)
- [What You Get with FerretDB v1](#what-you-get-with-ferretdb-v1)
- [Running FerretDB on Windows with Layerbase](#running-ferretdb-on-windows-with-layerbase)
  - [Option 1: Layerbase Desktop (GUI)](#option-1-layerbase-desktop-gui)
  - [Option 2: The Layerbase CLI](#option-2-the-layerbase-cli)
- [Hosted FerretDB with Layerbase Cloud](#hosted-ferretdb-with-layerbase-cloud)
- [Connecting with MongoDB Tools and Drivers](#connecting-with-mongodb-tools-and-drivers)
- [What About FerretDB v2?](#what-about-ferretdb-v2)
- [FAQ](#faq)
- [Wrapping Up](#wrapping-up)

## The Windows Problem: v1 vs v2

FerretDB has two major versions with fundamentally different architectures:

**FerretDB v1** stores documents in plain PostgreSQL using JSONB columns. The FerretDB process sits between your application and PostgreSQL, translating MongoDB wire protocol commands into SQL queries. It only needs a standard PostgreSQL server. Nothing platform-specific.

**FerretDB v2** moved document storage into `postgresql-documentdb`, a custom PostgreSQL extension written in C. This extension handles indexing, query planning, and document operations at the database level instead of in the FerretDB proxy. It's faster and more capable, but the extension only compiles on Linux. It depends on POSIX APIs and Linux-specific build tooling that don't have Windows equivalents.

The FerretDB team distributes Windows binaries for the FerretDB proxy itself, but without the `postgresql-documentdb` extension loaded into PostgreSQL, v2 won't start. You get a startup error because the required backend isn't available.

On Windows, your options are:

1. **Docker/WSL**: Run everything in a Linux environment. This works but defeats the purpose of running natively.
2. **FerretDB v1 via Layerbase**: Run the v1 proxy with a standard PostgreSQL backend. No extension needed, no Linux dependency.

## What You Get with FerretDB v1

FerretDB v1 supports the MongoDB operations that cover most application development needs:

- **CRUD**: `insertOne`, `insertMany`, `find`, `findOne`, `updateOne`, `updateMany`, `deleteOne`, `deleteMany`
- **Query operators**: `$eq`, `$gt`, `$lt`, `$in`, `$regex`, `$exists`, `$and`, `$or`, and more
- **Array operations**: `$elemMatch`, `$push`, `$pull`, `$addToSet`
- **Aggregation pipeline**: `$match`, `$group`, `$sort`, `$project`, `$limit`, `$skip`
- **Indexes**: `createIndex`, `dropIndex`, single-field and compound indexes
- **Database commands**: `listDatabases`, `listCollections`, `drop`, `ping`

The MongoDB wire protocol compatibility means `mongosh`, Compass, and every MongoDB driver library (Node.js, Python, Go, Java) connects to FerretDB v1 without changes.

Where v1 has limitations compared to v2: more complex aggregation stages, change streams, and some edge cases in query behavior. For local development and most application workloads, v1 covers what you need.

## Running FerretDB on Windows with Layerbase

Both Layerbase Desktop and the Layerbase CLI handle the complexity of running FerretDB by starting a PostgreSQL instance as the backend, configuring it, and starting FerretDB pointing at that PostgreSQL server. You don't need to set up PostgreSQL separately.

### Option 1: Layerbase Desktop (GUI)

[Layerbase Desktop](https://layerbase.com/desktop/download) makes this a point-and-click operation.

1. Download Layerbase Desktop from [layerbase.com/desktop/download](https://layerbase.com/desktop/download)
2. Open the app and click **Create Database**
3. Select **FerretDB** as the engine
4. Give it a name and click **Create**

The app sets up both FerretDB and its PostgreSQL backend automatically. You get a MongoDB connection URL that works with any MongoDB client.

### Option 2: The Layerbase CLI

[The Layerbase CLI](https://layerbase.com/docs/cli) gives you the same setup from the terminal. ([What is the Layerbase CLI?](https://layerbase.com/docs/cli))

Install the Layerbase CLI:

```bash
npm i -g layerbase
```

Create and start a FerretDB instance:

```bash
lbase create myferret -e ferretdb --start
```

The Layerbase CLI downloads the FerretDB binary and a PostgreSQL binary for Windows, initializes the PostgreSQL data directory, starts PostgreSQL, and starts FerretDB configured to use it as a backend. On Windows, the Layerbase CLI automatically uses FerretDB v1.

Get the connection URL:

```bash
lbase url myferret
```

```text
mongodb://127.0.0.1:27017/myferret
```

Manage the instance:

```bash
lbase stop myferret   # Stops both FerretDB and its PostgreSQL backend
lbase start myferret  # Starts both back up
lbase list            # See all instances
```

## Hosted FerretDB with Layerbase Cloud

This post focuses on native Windows development with FerretDB v1. If you want a managed MongoDB-compatible endpoint instead, FerretDB is also available on [Layerbase Cloud](https://cloud.layerbase.com/create?engine=ferretdb). Cloud FerretDB runs on Linux infrastructure with the PostgreSQL backend handled for you, plus TLS, backups, and connection details in the Quick Connect panel.

Use Layerbase Desktop or the Layerbase CLI when you want FerretDB running directly on your Windows machine. Use Layerbase Cloud when you want a hosted FerretDB endpoint your app can reach from anywhere.

## Connecting with MongoDB Tools and Drivers

FerretDB speaks the MongoDB wire protocol, so connect with any MongoDB tool or driver.

With `mongosh`:

```bash
mongosh "mongodb://127.0.0.1:27017/myferret"
```

```javascript
db.products.insertOne({
  name: 'Mechanical Keyboard',
  price: 149.99,
  tags: ['electronics', 'peripherals'],
  inStock: true,
})

db.products.find({ price: { $lt: 200 } })
```

With the Node.js MongoDB driver:

```typescript
import { MongoClient } from 'mongodb'

const client = new MongoClient('mongodb://127.0.0.1:27017/myferret')
await client.connect()

const db = client.db('myferret')
const products = db.collection('products')

await products.insertMany([
  { name: 'USB Hub', price: 29.99, tags: ['electronics'] },
  { name: 'Desk Lamp', price: 45.0, tags: ['office'] },
])

const results = await products.find({ tags: 'electronics' }).toArray()
console.log(results)

await client.close()
```

Everything works the same way it would against a MongoDB server. The difference is that your data is stored in PostgreSQL tables, which you can also query directly with SQL if you need to.

## What About FerretDB v2?

We're actively working on bringing FerretDB v2 to Windows. The blocker is `postgresql-documentdb`, the PostgreSQL extension that v2 requires. This extension is written in C with Linux-specific dependencies, and porting it to Windows is a non-trivial effort.

We haven't given up on this. We're exploring compilation approaches and working to understand exactly which dependencies need to be addressed. If and when we get v2 working on Windows, it will be available through the Layerbase CLI and Layerbase Desktop automatically.

In the meantime, FerretDB v1 is a fully functional MongoDB-compatible database for Windows development. On macOS and Linux, the Layerbase CLI runs FerretDB v2 by default and takes advantage of the `postgresql-documentdb` backend.

## FAQ

### Why can't FerretDB v2 run on Windows?

Because v2 moved document storage into `postgresql-documentdb`, a PostgreSQL extension written in C that depends on POSIX APIs and Linux build tooling. The FerretDB team does ship a Windows binary for the proxy, but without that extension loaded into PostgreSQL, v2 fails at startup because its backend is not there.

### What do I give up by running v1 instead?

Performance and some newer capability. v2 pushes indexing, query planning, and document operations down into the database through the extension, where v1 translates MongoDB wire protocol commands into SQL in the proxy. For Windows development work the practical difference is speed rather than whether your code runs.

### Does my application code change?

No. You connect with `mongosh` and standard MongoDB drivers against a `mongodb://` connection string either way. The visible difference is on the storage side: your documents are rows in PostgreSQL, which you can also query with SQL if it is ever useful.

### Should I use this for production on Windows?

Use it for development. If you want FerretDB backing a running application, the sensible path is a hosted FerretDB endpoint, where v2 runs on Linux with the extension and you do not maintain the PostgreSQL backend yourself. Your Windows machine connects to it with the same driver.

### Will v2 come to Windows?

We are working on it, and the honest status is that porting the extension is a real piece of work rather than a configuration problem. If it lands, it arrives through the Layerbase CLI and Layerbase Desktop without you doing anything. Until then, macOS and Linux run v2 by default and Windows runs v1.

## Wrapping Up

FerretDB gives you the MongoDB API without the MongoDB license. On Linux and macOS, FerretDB v2 runs with full `postgresql-documentdb` performance. On Windows, the required extension isn't available yet, but FerretDB v1 runs natively through our custom binaries and covers the MongoDB operations you need for development.

[Layerbase Desktop](https://layerbase.com/desktop/download) sets up FerretDB and its PostgreSQL backend with a few clicks. [The Layerbase CLI](https://layerbase.com/docs/cli) does the same from the command line. [Layerbase Cloud](https://cloud.layerbase.com/create?engine=ferretdb) gives you a hosted FerretDB endpoint when you do not want to manage the backend yourself.

FerretDB is one of over 20 engines available through the Layerbase CLI and Layerbase Desktop. See the full list at [layerbase.com/docs/cli](https://layerbase.com/docs/cli).