Developing Open WebUI

Work on dev, never on main

dev is the pre-release branch, and everything lands there first. Every fix and every feature goes to dev and stays there, so a bug fixed today is on dev today and reaches main at the next release. main is a snapshot of dev taken on release day, which means building from main gives you code that is already behind.

A fresh git clone puts you on main. Switch before you do anything else:

git clone https://github.com/open-webui/open-webui.git
cd open-webui
git checkout dev

Pull requests are opened against dev as well. One opened against main has to be redone.

Run Open WebUI from source for development and testing.

This guide covers setting up a local development environment with the frontend (SvelteKit) and backend (Python/FastAPI) running side by side. You will need two terminal sessions, one for each.

Don't need a full dev environment?

Run the :dev pre-release image instead. It is the same code, rebuilt nightly as changes land, with nothing for you to build:

docker run -d -p 3001:8080 --add-host=host.docker.internal:host-gateway -v open-webui-dev:/app/backend/data -e WEBUI_SECRET_KEY=your-secret-key --name open-webui-dev --restart always ghcr.io/open-webui/open-webui:dev

Testing it and reporting what you find is the lowest-effort way to help, and it is what makes releases good. See Using the Dev Branch for the details, and note the separate volume.

---

Prerequisites

Requirement	Version
Python	3.11 or 3.12 (see note below; 3.13 not supported yet)
Node.js	22.10+
Git	Any recent version

Python version compatibility

Open WebUI supports Python 3.11 and 3.12. 3.13 is not supported yet: a few of our dependencies still need to ship 3.13-compatible releases, and until they do, installs on 3.13 will fail or break at runtime.

• For production, use the Docker image or the latest Python 3.11. This is the combination we test against most heavily.
• 3.12 also works, but we have seen very rare reports of odd behaviour on 3.12 that we have not reproduced on 3.11. If you are running into something inexplicable on 3.12, dropping to the latest 3.11 is the first thing to try.

Separate your data

Never share your database or data directory between dev and production. Dev builds may include database migrations that are not backward-compatible.

---

1. Clone the repository

git clone https://github.com/open-webui/open-webui.git
cd open-webui
git checkout dev

git checkout dev is the important line. Without it you are building the last release rather than the current code.

---

2. Frontend setup

In your first terminal, from the project root:

cp -RPp .env.example .env
npm install
npm run build
npm run dev

npm run build compiles the frontend and catches build-time errors early. npm run dev then starts the dev server at http://localhost:5173. It will show a waiting screen until the backend is running.

tip

If npm install fails with compatibility warnings, run npm install --force.

---

3. Backend setup

In your second terminal:

cd backend

Create and activate a virtual environment (Conda or venv):

# Option A: Conda
conda create --name open-webui python=3.11
conda activate open-webui

# Option B: venv
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

Install dependencies and start the server:

pip install -r requirements.txt -U
sh dev.sh

The backend starts at http://localhost:8080. API docs are available at http://localhost:8080/docs.

Refresh the frontend at http://localhost:5173 and you should see the full application.

---

Testing from another device

To access your dev instance from a phone or another computer on the same network:

1. Find your machine's LAN IP (e.g., 192.168.1.42)
2. Add the origin to CORS in backend/dev.sh:

export CORS_ALLOW_ORIGIN="http://localhost:5173;http://localhost:8080;http://192.168.1.42:5173"

3. Restart the backend and browse to http://192.168.1.42:5173

---

Troubleshooting

"FATAL ERROR: Reached Heap Limit"

Node.js is running out of memory during the build. Increase the heap size before running frontend commands:

export NODE_OPTIONS="--max-old-space-size=4096"
npm run dev

Ensure at least 4 GB of RAM is available.

Port conflicts

If port 5173 or 8080 is already in use, find the conflicting process:

# macOS/Linux
lsof -i :5173

# Windows (PowerShell)
Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess

Terminate the process or change the port in vite.config.js (frontend) or dev.sh (backend).

Icons not loading (CORS)

If static assets fail to load, configure CORS_ALLOW_ORIGIN in backend/dev.sh to include your frontend URL. See CORS configuration for details.

Hot reload not working

1. Verify both dev servers are running without errors
2. Hard refresh the browser (Ctrl+Shift+R / Cmd+Shift+R)
3. Reinstall frontend dependencies: rm -rf node_modules && npm install
4. Backend changes may require manually restarting sh dev.sh

---

Contributing workflow

1. Open a discussion first at GitHub Discussions before writing code
2. Create a branch from dev for your work. Never commit directly to dev.

git checkout dev
git pull origin dev
git checkout -b my-feature-branch

3. Keep your branch synced by periodically merging from dev
4. Submit a pull request to the dev branch with a clear title and description

For contribution guidelines, see Contributing.