These are steps specifically for Windows, or to make it easier for you you may also easily run this within umbrelOS which is a personal server operating system to make this process easy too, they are two different options, the Umbrel is a more user-friendly optimized version you may find here: https://apps.umbrel.com/app/btcpay-server
Second option is for Windows and BTCPayServer on a computer that is not designed as a personal server so if the computer goes off for any reason, you lose access to the store, these are the steps and the main point of this repository for Linux on Windows to run BTCPayServer that anyone can do by following these steps to learn: Self-host a Bitcoin checkout on a Windows PC. Accept on-chain and Lightning payments without Shopify, without a payment processor, and without giving a third party custody of your coins.
BTCPay Server has no native Windows installer. The supported production setup is Docker on Linux. On Windows that means WSL (Ubuntu or Debian) for a real shop, or PowerShell + Docker Desktop if you only want a local test instance.
This is a practical Windows walkthrough. The upstream project and official docs live at btcpayserver.org and docs.btcpayserver.org/Docker.
- What you get
- Which path to take
- Install Linux on Windows (WSL)
- Enter Ubuntu from PowerShell
- Install BTCPay Server (production)
- Local test install (regtest, no domain)
- After it is running
A self-hosted stack that can run a full Bitcoin node (pruned, ~50 GB with the options below), NBXplorer, PostgreSQL, BTCPay Server, nginx with HTTPS, and Core Lightning. You point a domain at the machine, create a store, and take payment the way a Shopify shop would — except you own the server and the keys.
You need:
- A Windows 10/11 PC that can run WSL 2 (virtualization enabled in BIOS/UEFI)
- A domain whose A record points at this machine
- Ports 80 and 443 reachable from the internet (Lightning also needs 9735)
- Disk space for the chain (plan on 50 GB+ for the pruned node in this guide)
| Goal | Use |
|---|---|
| Real shop / mainnet node | WSL (Ubuntu or Debian) + the official btcpay-setup.sh |
| Try the UI on this PC with no domain | PowerShell + Docker Desktop (regtest) |
Three reliable ways. Use Ubuntu or Debian — both work for BTCPay. After any of these, confirm with wsl -l -v in PowerShell, then enter the distro with wsl -d Ubuntu or wsl -d Debian.
1. PowerShell one-command install (Microsoft’s default). Open PowerShell as Administrator and run wsl --install -d Ubuntu (or wsl --install -d Debian if you prefer Debian). This turns on the WSL Windows features, installs the WSL kernel, and downloads that distro; reboot if Windows asks, then Ubuntu/Debian will start and prompt you for a Linux username and password. Confirm it worked with wsl -l -v, then enter the distro with wsl -d Ubuntu or wsl -d Debian.
2. Microsoft Store (WSL app, then Ubuntu or Debian). On a reset or stubborn PC, open the Microsoft Store, install Windows Subsystem for Linux, then search the Store for Ubuntu or Debian and install the distro you want (either works for BTCPay). Launch Ubuntu or Debian from the Start menu once; the first run finishes setup and asks for a Linux username and password. After that you can also open it from PowerShell with wsl -d Ubuntu or wsl -d Debian. If the Store distro says WSL is not enabled, run wsl --install --no-distribution in Administrator PowerShell, reboot, and open the distro again.
3. Turn on Windows features first, then add a distro (best fallback). If wsl --install errors or the Store app will not start, enable Virtual Machine Platform and Windows Subsystem for Linux under Windows Features (or in Administrator PowerShell: dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart and dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart), reboot, then run wsl --update and install Ubuntu or Debian from the Store. Also turn on virtualization in BIOS/UEFI if Windows reports that the hypervisor is not available; without that, no WSL method will work.
You do not need Windows Terminal. If you are already in PowerShell, stay there:
wsl -l -vYou want Ubuntu (or Debian) with state Running or Stopped. Then:
wsl -d UbuntuIf it is the only (or default) distro:
wslThe first launch asks for a Linux username and password. That password is for sudo later. It will not echo as you type; that is normal.
You are in Linux when the prompt changes from:
PS C:\Users\YourName>
to:
username@PCNAME:~$
Paste the BTCPay commands only after you see that $ prompt.
If wsl -l -v says there are no installed distributions, or wsl is not recognized, go back to Install Linux on Windows (WSL) and finish that first.
Optional: press the Windows key, type Ubuntu, and press Enter. Or, if you have Windows Terminal, click the dropdown next to + and choose Ubuntu. Neither is required if wsl -d Ubuntu already dropped you into a $ prompt.
In the Ubuntu (or Debian) shell:
sudo su -
mkdir -p ~/BTCPayServer
cd ~/BTCPayServer
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker
export BTCPAY_HOST="btcpay.YOURDOMAIN.com"
export NBITCOIN_NETWORK="mainnet"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage-s"
export BTCPAYGEN_REVERSEPROXY="nginx"
export BTCPAYGEN_LIGHTNING="clightning"
export BTCPAY_ENABLE_SSH=true
. ./btcpay-setup.sh -iReplace btcpay.YOURDOMAIN.com with your real hostname. opt-save-storage-s prunes Bitcoin to about 50 GB (roughly six months of blocks). Drop that fragment if you want a full node and have the disk.
The setup script installs Docker, generates compose, and starts BTCPay.
Useful later, in the same Linux shell:
btcpay-up.sh # start
btcpay-down.sh # stop
btcpay-restart.sh # restart
btcpay-update.sh # updateOfficial Docker guide: docs.btcpayserver.org/Docker
Use this only to try the interface on this Windows PC. It is not a mainnet payment processor.
In PowerShell:
winget install -e --id Git.Git
winget install -e --id Docker.DockerDesktop
winget install -e --id Microsoft.DotNet.SDK.10Start Docker Desktop, then:
git clone https://github.com/btcpayserver/btcpayserver.git
cd btcpayserver\BTCPayServer.Tests
docker compose up -d dev
cd ..\BTCPayServer
dotnet run --launch-profile BitcoinOpen http://127.0.0.1:14142.
Stop later with:
cd ..\BTCPayServer.Tests
docker compose down- Open
https://btcpay.YOURDOMAIN.com(production) orhttp://127.0.0.1:14142(regtest). - Register the first account — that user becomes the server admin.
- Create a store, attach a wallet (on-chain and/or Lightning), and create an invoice or point-of-sale app.
The node has to sync before mainnet invoices confirm. A pruned first sync still takes time; leave the machine on.
This repository is a Windows-oriented setup guide. BTCPay Server is MIT-licensed open source software maintained by the BTCPay Server project. Follow their docs for upgrades, security, and production hardening.