Skip to main content

πŸ› οΈ Development Guide

Welcome to the Open WebUI Development Setup Guide! Whether you're a novice or an experienced developer, this guide will help you set up a local development environment for both the frontend and backend components. Let’s dive in! πŸš€

System Requirements​

  • Operating System: Linux (or WSL on Windows) or macOS
  • Python Version: Python 3.11+
  • Node.js Version: 22.10+

Development Methods​

🐧 Local Development Setup​

  1. Clone the Repository:

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

  2. Frontend Setup:

    • Create a .env file:

      cp -RPp .env.example .env

    • Install dependencies:

      npm install

    • Start the frontend server:

      npm run dev

      🌐 Available at: http://localhost:5173.

  3. Backend Setup:

    • Navigate to the backend:

      cd backend

    • Use Conda for environment setup:

      conda create --name open-webui python=3.11
      conda activate open-webui

    • Install dependencies:

      pip install -r requirements.txt -U

    • Start the backend:

      sh dev.sh

      πŸ“„ API docs available at: http://localhost:8080/docs.

πŸ› Troubleshooting​

FATAL ERROR: Reached Heap Limit​

If you encounter memory-related errors during the build, increase the Node.js heap size:

  1. Modify Dockerfile:

    ENV NODE_OPTIONS=--max-old-space-size=4096

  2. Allocate at least 4 GB of RAM to Node.js.

Other Issues​

  • Port Conflicts:
    Ensure that no other processes are using ports 8080 or 5173.

  • Hot Reload Not Working:
    Verify that watch mode is enabled for both frontend and backend.

Contributing to Open WebUI​

Local Workflow​

  1. Commit Changes Regularly to track progress.

  2. Sync with the Main Branch to avoid conflicts:

    git pull origin main

  3. Run Tests Before Pushing:

    npm run test

Happy coding! πŸŽ‰