Quick Start

Get started with Open WebUI from installation to your first chat in minutes

Quick Start Guide

This guide will walk you through getting Open WebUI up and running quickly, from installation to your first conversation with an AI model.

Prerequisites

Before you begin, ensure you have one of the following:

• Docker installed (recommended)
• Python 3.11 or 3.12 for pip installation
• A running Ollama instance (optional, for local models)

---

Step 1: Choose Your Installation Method

Docker (Recommended)

The fastest way to get started is with Docker and the bundled Ollama image:

With GPU

docker run -d -p 3000:8080 \
  --gpus=all \
  -v ollama:/root/.ollama \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:ollama

Wait for the container to start, then navigate to http://localhost:3000

Docker Compose

Create a docker-compose.yaml file:

services:
  ollama:
    volumes:
      - ollama:/root/.ollama
    container_name: ollama
    pull_policy: always
    tty: true
    restart: unless-stopped
    image: ollama/ollama:latest

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    volumes:
      - open-webui:/app/backend/data
    depends_on:
      - ollama
    ports:
      - 3000:8080
    environment:
      - 'OLLAMA_BASE_URL=http://ollama:11434'
    extra_hosts:
      - host.docker.internal:host-gateway
    restart: unless-stopped

volumes:
  ollama: {}
  open-webui: {}

Start the services:

docker compose up -d

Navigate to http://localhost:3000

Python pip

Install Open WebUI using pip:

pip install open-webui

Start the server:

open-webui serve

Navigate to http://localhost:8080

---

Step 2: Create Your Admin Account

1. Access the Web Interface

   Open your browser and navigate to:

   • Docker: http://localhost:3000
   • pip: http://localhost:8080
2. Sign Up

   On first launch, you’ll see the signup page. Create your admin account:

   • Name: Your display name
   • Email: Your email address (used for login)
   • Password: A secure password

   The first user to sign up automatically becomes the administrator.

3. Sign In

   After creating your account, sign in with your credentials.

---

Step 3: Set Up Your First Model

Using Ollama

If you’re using the bundled Ollama image or have Ollama running, you can pull models directly from the UI.

1. Access Settings

   Click on your profile icon in the top-right corner and select Settings.

2. Navigate to Models

   Go to the Admin Panel → Settings → Models section.

3. Pull a Model

   In the model pull section, enter a model name (e.g., llama3.2 or mistral) and click Pull Model.

   Popular models to start with:

   • llama3.2 - Meta’s latest Llama model
   • mistral - Mistral AI’s efficient model
   • phi3 - Microsoft’s compact model
   • gemma2 - Google’s Gemma model
4. Wait for Download

   The model will download and become available once complete. This may take a few minutes depending on the model size and your internet connection.

Using OpenAI API

If you’re using OpenAI or another compatible API:

1. Access Settings

   Click on your profile icon and select Settings.

2. Add API Connection

   Go to Admin Panel → Settings → Connections.

3. Configure OpenAI

   Enable the OpenAI API connection and enter:

   • API Key: Your OpenAI API key
   • API Base URL: https://api.openai.com/v1 (or your custom endpoint)
4. Save Settings

   Click Save to apply the configuration.

You can also set the API key via environment variable:

-e OPENAI_API_KEY=your_secret_key

---

Step 4: Start Your First Chat

1. Create a New Chat

   Click the + New Chat button on the sidebar or in the center of the screen.

2. Select a Model

   Click on the model selector dropdown at the top of the chat interface and choose your preferred model.

3. Send Your First Message

   Type a message in the text box at the bottom and press Enter or click the send button.

   Example prompts to try:

   • “Explain quantum computing in simple terms”
   • “Write a Python function to reverse a string”
   • “What are the best practices for Docker deployments?”
4. Explore Features

   Try these features in your chat:

   • Multi-line input: Press Shift+Enter for new lines
   • Regenerate: Click the regenerate button to get a different response
   • Copy: Copy responses with the copy button
   • Voice input: Click the microphone icon for voice-to-text

---

Step 5: Explore Advanced Features

Now that you have Open WebUI running, explore these powerful features:

Document Upload

Upload documents and ask questions about their content using the RAG feature. Click the + icon in the chat input to upload files.

Web Search

Enable web search to get real-time information. Type # followed by a search query or URL.

Multiple Models

Compare responses from multiple models simultaneously by selecting multiple models from the dropdown.

Custom Prompts

Create and save custom prompts for repeated tasks in the Workspace section.

---

Common Tasks

Upload and Query Documents

1. Enable RAG

   RAG (Retrieval Augmented Generation) is enabled by default.

2. Upload Document

   Click the + icon next to the chat input and select Upload Files. Choose your document (PDF, TXT, DOCX, etc.).

3. Ask Questions

   Once uploaded, ask questions about the document:

   • “Summarize this document”
   • “What are the key points in section 3?”
   • “Extract the main findings”

Create a Custom Model

1. Access Workspace

   Click Workspace in the sidebar, then navigate to Models.

2. Create Model

   Click + Create Model and configure:

   • Base Model: Select the foundation model
   • System Prompt: Define the model’s behavior
   • Parameters: Adjust temperature, top_p, etc.
3. Save and Use

   Save your custom model and select it from the model dropdown in any chat.

Enable Web Search

1. Configure Search Provider

   Go to Admin Panel → Settings → Web Search.

2. Select Provider

   Choose a search provider (SearXNG, Google PSE, Brave Search, DuckDuckGo, etc.) and configure any required API keys.

3. Use in Chat

   In your chat, type # followed by a search query to inject web results into the conversation.

---

Configuration Quick Reference

Environment Variables

Set these via Docker -e flag or in your environment:

# Ollama connection
OLLAMA_BASE_URL=http://localhost:11434

# OpenAI API
OPENAI_API_KEY=your_secret_key
OPENAI_API_BASE_URL=https://api.openai.com/v1

# Security
WEBUI_SECRET_KEY=your_secret_key

# Disable signup after initial setup
ENABLE_SIGNUP=False

Admin Settings Location

Access admin settings at:

1. Click your profile icon (top-right)
2. Select Admin Panel
3. Navigate to Settings

Key sections:

• General: Basic configuration
• Models: Model management and settings
• Connections: External API connections
• Users: User management and permissions

---

Troubleshooting

Models not appearing

Solution:

1. Verify Ollama is running: docker ps | grep ollama
2. Check the OLLAMA_BASE_URL environment variable
3. Ensure models are pulled: docker exec -it ollama ollama list

Cannot connect to Ollama

Solution:

1. If using separate containers, ensure they’re on the same network
2. Use --add-host=host.docker.internal:host-gateway for local Ollama
3. For bundled installation, no additional configuration needed

Slow model responses

Solution:

1. Use smaller models (phi3, mistral) for faster responses
2. Enable GPU support with --gpus all and :cuda image
3. Adjust model parameters (lower temperature, max_tokens)

Login issues

Solution:

1. Clear browser cache and cookies
2. Verify WEBUI_SECRET_KEY is set and consistent
3. Check browser console for errors (F12)

---

Next Steps

Configuration Guide

Learn about all configuration options and environment variables

Features Overview

Explore all features including RAG, web search, and image generation

User Management

Set up user roles, permissions, and access control

API Reference

Integrate Open WebUI with your applications

---

Tips for Success

Disable Signup After Setup: Once you’ve created accounts for your users, disable signup to prevent unauthorized access:

-e ENABLE_SIGNUP=False

Use Persistent Storage: Always use volume mounts to prevent data loss:

-v open-webui:/app/backend/data

Start Small: Begin with smaller models like phi3 or mistral to test the setup before downloading larger models.

Need help? Join our Discord community or check the full documentation.