Installation FAQ

Common questions about installing, updating, maintaining, and troubleshooting LNbits startup issues.

• What are the system requirements?
• Which installation method should I use?
• Can I run LNbits on a Raspberry Pi?
• Can I run LNbits on Windows?
• Docker vs bare metal - which should I choose?
• How do I update LNbits?
• How do I backup LNbits?
• How do I migrate from SQLite to PostgreSQL?
• LNbits won't start - port conflict
• LNbits won't start - database connection error
• LNbits won't start - Python version mismatch
• Docker container keeps restarting
• Docker permission issues
• Related Pages

What are the system requirements?

• Minimum: 1 CPU, 512 MB RAM, 1 GB disk (SQLite)
• Recommended: 2 CPU, 2 GB RAM, PostgreSQL
• Python 3.10+ or Docker

For production use, PostgreSQL is strongly recommended over SQLite. See Installation for details.

Which installation method should I use?

It depends on your environment:

Method	Best for
Docker	Production, easy setup, isolation
uv	Fast bare-metal install, development
Poetry	Development, contribution
Nix	NixOS users, reproducible builds
AppImage	Desktop Linux, quick testing
Node platforms	Raspberry Pi, Umbrel, Start9, myNode
SaaS	Zero setup, hosted instances
Fly.io	Cloud deployment

See the installation decision tree for a guided choice.

Can I run LNbits on a Raspberry Pi?

Yes. LNbits runs well on a Raspberry Pi 4 (2 GB+ RAM). The easiest methods are:

• Umbrel / Start9 / myNode - one-click install from the app store
• Docker - docker compose up on Raspberry Pi OS
• uv / Poetry - bare-metal install with Python 3.10+

A Pi 3 may work but is not recommended for production. See Node Platforms.

Can I run LNbits on Windows?

Yes, using Docker Desktop or WSL2 (Windows Subsystem for Linux). Docker is the easiest path - install Docker Desktop for Windows and follow the Docker guide.

For bare-metal installs, use WSL2 with Ubuntu and follow the standard Linux instructions.

Docker vs bare metal - which should I choose?

	Docker	Bare metal
Setup	Easier (pre-configured)	More manual steps
Updates	docker compose pull && up	git pull + dependency install
Isolation	Fully containerized	Shares system Python
Debugging	Slightly harder (logs via docker)	Direct access to files/logs
Performance	Minimal overhead	Slightly faster
Best for	Production, beginners	Development, advanced users

How do I update LNbits?

The update process depends on your installation method. See Updating for step-by-step instructions for every method (Docker, uv, Poetry, Nix, AppImage, Fly.io).

Always back up before updating - especially your .env file and database.

How do I backup LNbits?

Back up these items:

1. .env file - your configuration
2. Database - SQLite file (./data/database.sqlite3) or PostgreSQL dump
3. Data directory - ./data/ contains extension data and uploaded files

# SQLite backup
cp data/database.sqlite3 data/database.sqlite3.bak

# PostgreSQL backup
pg_dump lnbits > lnbits_backup.sql

How do I migrate from SQLite to PostgreSQL?

LNbits includes a built-in migration tool:

# 1. Set your PostgreSQL connection in .env
LNBITS_DATABASE_URL=postgres://user:password@localhost:5432/lnbits

# 2. Run the migration command
poetry run python tools/conv.py

See PostgreSQL for full setup instructions.

LNbits won't start - port conflict

ERROR: [Errno 98] Address already in use

Another process is using port 5000. Either stop the conflicting process or change the LNbits port:

# In .env
PORT=5001

To find what's using the port:

lsof -i :5000
# or
ss -tlnp | grep 5000

LNbits won't start - database connection error

ERROR: connection to server at "localhost" failed

Check that:

1. PostgreSQL is running: sudo systemctl status postgresql
2. The connection string in .env is correct: LNBITS_DATABASE_URL=postgres://user:password@localhost:5432/lnbits
3. The database exists: psql -l | grep lnbits
4. The user has proper permissions

LNbits won't start - Python version mismatch

LNbits requires Python 3.10+. Check your version:

python3 --version

If your system Python is too old, install a newer version or use uv which manages Python versions automatically.

Docker container keeps restarting

Check the logs for the root cause:

docker compose logs lnbits

Common causes:

• Bad .env configuration - check all required variables are set
• Database connection issues - ensure the database container is running and healthy
• Port conflicts - another service is using the same port
• Missing data directory - ensure ./data/ exists and has proper permissions

Docker permission issues

If you see permission denied errors on the data directory:

sudo chown -R 1000:1000 ./data

The LNbits Docker container runs as UID 1000 by default. Ensure the data directory is owned by this user.

Related Pages

• Installation - choose your setup method
• Updating - update instructions for all methods
• PostgreSQL - database setup
• First Setup - post-install configuration