Skip to content

Install on Windows

Run Embedder in a Linux environment on Windows: Docker Desktop with WSL 2, or directly inside WSL 2. The repository's make setup uses Bash and venv/bin, so do not run those commands unchanged in PowerShell.

Prepare WSL 2

Open PowerShell as Administrator and run:

wsl --install -d Ubuntu

Restart if prompted, open Ubuntu, and create your Linux user. In PowerShell, update and check WSL:

wsl --update
wsl --list --verbose

Ubuntu should show 2 in the VERSION column. If it shows 1, run wsl --set-version Ubuntu 2, using the exact distribution name from the list. See Microsoft's installation guide for Windows requirements and troubleshooting.

Option 1: CPU in Docker Desktop

Install Docker Desktop for Windows. Enable the WSL 2 engine and Ubuntu integration in its settings, and use Linux containers.

Run these commands in the Ubuntu terminal, not PowerShell:

sudo apt-get update
sudo apt-get install -y git curl
git clone https://github.com/dzenplatform/embedder.git
cd embedder
docker compose version
docker compose up -d
docker compose logs -f model-init embedder

The first start downloads the model into a persistent Docker volume. If docker is unavailable inside Ubuntu, check Docker Desktop's WSL integration.

Option 2: NVIDIA GPU in Docker Desktop

You need an NVIDIA GPU, an up-to-date Windows driver with WSL support, and Docker Desktop using its WSL 2 backend. Install the driver in Windows. Follow Docker's GPU requirements and setup guide.

Check the card with nvidia-smi in Ubuntu. From the repository directory, use the CUDA variant instead of the CPU command:

docker compose -f compose.yaml -f compose.cuda.yaml up -d
docker compose -f compose.yaml -f compose.cuda.yaml logs -f model-init embedder

Compose selects the 0.1.0-cu126 Linux amd64 image and GPU 0. Remove any CPU override from EMBEDDER_TAG. Your GPU must work with the image's CUDA 12.6 and PyTorch 2.6.0 stack; Docker Desktop does not remove that compatibility requirement.

This path uses Docker Desktop. Do not apply standalone Linux Docker Engine runtime configuration commands to its managed engine without checking Docker Desktop's instructions.

Option 3: CPU directly in WSL 2

Docker is optional. In Ubuntu, install Git, make, curl, and uv:

sudo apt-get update
sudo apt-get install -y git make curl
curl -LsSf https://astral.sh/uv/install.sh | sh

Close and reopen the Ubuntu terminal:

uv --version
git clone https://github.com/dzenplatform/embedder.git
cd embedder
DEVICE=cpu make setup
DEVICE=cpu make run

If the repository already exists, enter it instead of cloning again. The Makefile creates a Linux venv/ environment with Python 3.12. For GPU use on Windows, follow the Docker Desktop option above.

Verify the installation

In a second Ubuntu terminal, run the readiness check and embedding request. To access the service from Windows, try http://localhost:8091/docs in your browser. If it works inside Ubuntu but not from Windows, check WSL networking and local firewall rules.