# How to Enable and Customize the Gradio User Interface for Testing and Interaction in Private‑GPT

> Learn to enable and customize the Gradio User Interface in Private-GPT. Easily configure settings and run the application for seamless interaction and testing.

- Repository: [Zylon/private-gpt](https://github.com/zylon-ai/private-gpt)
- Tags: how-to-guide
- Published: 2026-03-06

---

**To enable the Gradio UI in Private‑GPT, set `ui.enabled: true` in your configuration file, adjust the `path`, `default_mode`, and system prompts under the `ui` section, then run `python -m private_gpt.main` to mount the interface at the configured endpoint.**

The **Gradio** web interface in the [zylon-ai/private-gpt](https://github.com/zylon-ai/private-gpt) repository provides a visual way to test RAG (Retrieval-Augmented Generation), search, and summarization modes without writing API calls. By default, the UI is disabled and must be activated through YAML configuration, after which it exposes a fully customizable frontend mounted on your FastAPI application.

## Enabling the Gradio Interface

The UI is controlled by the **UISettings** class defined in [[`private_gpt/settings/settings.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/settings/settings.py)](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/settings/settings.py). To activate the interface, locate your active configuration file (for example, [`private_gpt.yaml`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt.yaml), [`settings.yaml`](https://github.com/zylon-ai/private-gpt/blob/main/settings.yaml), or a profile-specific file) and add or modify the `ui` block.

Set **`enabled`** to `true` and define the **`path`** where the interface will be served:

```yaml
ui:
  enabled: true          # Enable the web interface

  path: "/ui"            # URL route where Gradio will be mounted

```

If `enabled` remains `false` (the default), the launcher will skip mounting the UI entirely, making the backend API-only.

## Configuring UI Behavior and Defaults

Once enabled, you can customize interaction defaults through the same configuration section. The model exposes several fields that populate the initial state of the Gradio components in [[`private_gpt/ui/ui.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py)](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py).

### Default Mode Selection

Specify which operating mode the UI should start in using **`default_mode`**. Valid values correspond to the application’s ingestion strategies:

```yaml
ui:
  default_mode: "RAG"    # Options: RAG, Search, Basic, Summarize

```

### System Prompts

Pre-load default system instructions for different interaction types using the following keys. These strings populate the system prompt text boxes when the UI initializes:

```yaml
ui:
  default_chat_system_prompt: "You are a helpful AI assistant."
  default_query_system_prompt: "Answer the question based only on the provided context."
  default_summarization_system_prompt: "Provide a concise summary of the following content."

```

### File Management Controls

Toggle visibility of destructive file actions with boolean flags. When set to `false`, the corresponding buttons are hidden from the interface:

```yaml
ui:
  delete_file_button_enabled: true       # Show/hide single file delete

  delete_all_files_button_enabled: false # Show/hide delete all files

```

These values are passed directly to the `visible` parameter of Gradio `Button` components in the UI building logic.

## Launching the Interface

After updating your configuration, you have two methods to start the interface depending on whether you need the full API backend or just the frontend.

### Full Server Mode (Recommended)

Run the main application to start the FastAPI server with the UI automatically mounted at the configured path:

```bash
python -m private_gpt.main

```

Alternatively, using Uvicorn directly:

```bash
uvicorn private_gpt.main:app --host 0.0.0.0 --port 8001

```

The launcher code in [[`private_gpt/launcher.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/launcher.py)](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/launcher.py) checks `settings().ui.enabled` and, if true, calls `blocks.mount_gradio_app(app, path=settings().ui.path)` to integrate the Gradio blocks with the FastAPI application.

### Standalone UI Mode (Testing Only)

For rapid frontend iteration without the full backend ingestion pipeline, execute the UI module directly:

```bash
python -m private_gpt.ui.ui

```

This invokes the `if __name__ == "__main__"` block at the bottom of [[`private_gpt/ui/ui.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py)](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py), launching Gradio on its own local server (typically `http://127.0.0.1:7860`). Note that this mode runs the UI in isolation and may lack full backend functionality unless properly initialized.

## Customizing the Theme and Styling

Visual customization is handled within [[`private_gpt/ui/ui.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py)](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py). The interface uses the **`gr.themes.Soft`** theme with a slate primary hue by default.

To modify the color scheme, locate the `gr.Blocks` constructor (typically inside the `_build_ui_blocks` method or similar) and adjust the theme parameters:

```python

# In private_gpt/ui/ui.py

theme = gr.themes.Soft(primary_hue="teal")  # Change from slate to teal

with gr.Blocks(title="Private‑GPT", theme=theme, css=...) as blocks:
    # UI definition continues...

```

For deeper styling, edit the embedded CSS string passed to the `css` parameter. This allows you to adjust logo dimensions, header backgrounds, chat bubble colors, and footer layouts without altering the core application logic.

## Key Source Files and Architecture

Understanding the codebase structure helps with advanced customizations:

- **[[`private_gpt/settings/settings.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/settings/settings.py)](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/settings/settings.py)** – Contains the **UISettings** Pydantic model that validates all `ui.*` configuration keys.
- **[[`private_gpt/launcher.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/launcher.py)](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/launcher.py)** – Orchestrates application startup; conditionally mounts the Gradio app based on `settings().ui.enabled`.
- **[[`private_gpt/main.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/main.py)](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/main.py)** – Entry point that initializes the FastAPI application and triggers the launcher.
- **[[`private_gpt/ui/ui.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py)](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py)** – Core UI implementation including Gradio blocks, callback handlers, file upload/delete logic, and mode switching.
- **[[`private_gpt/ui/images.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/images.py)](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/images.py)** – Stores the SVG logo and other image assets rendered in the header.

## Summary

- Set **`ui.enabled: true`** in your YAML configuration to activate the Gradio interface.
- Customize the mount **`path`**, **`default_mode`**, and **`system prompts`** through the `ui` configuration section.
- Control file management visibility with **`delete_file_button_enabled`** and **`delete_all_files_button_enabled`** flags.
- Launch the full stack with `python -m private_gpt.main` or test the UI standalone with `python -m private_gpt.ui.ui`.
- Modify visual themes and CSS in [[`private_gpt/ui/ui.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py)](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py) to match your branding.

## Frequently Asked Questions

### How do I change the default chat mode from RAG to Basic?

Set **`ui.default_mode: "Basic"`** in your configuration file. Valid options are `RAG`, `Search`, `Basic`, and `Summarize`, which correspond to the different interaction modes defined in the ingestion service. Restart the server after saving the configuration change.

### Where can I hide the delete file buttons for safety?

In your configuration YAML, set **`ui.delete_file_button_enabled: false`** and **`ui.delete_all_files_button_enabled: false`**. These booleans control the `visible` attribute of the Gradio Button components in [[`private_gpt/ui/ui.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py)](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py), completely removing the UI elements rather than just disabling them.

### What is the difference between running [`main.py`](https://github.com/zylon-ai/private-gpt/blob/main/main.py) and [`ui.py`](https://github.com/zylon-ai/private-gpt/blob/main/ui.py) directly?

Running **`python -m private_gpt.main`** starts the complete FastAPI application with all API routes, ingestion workers, and the Gradio UI mounted as a sub-application. Running **`python -m private_gpt.ui.ui`** executes only the Gradio frontend code via the `if __name__ == "__main__"` block, which is useful for rapid UI prototyping but does not initialize the full backend context database or ingestion pipeline.

### How do I customize the Gradio theme colors?

Edit the theme instantiation in [[`private_gpt/ui/ui.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py)](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py). Change the `primary_hue` parameter in `gr.themes.Soft(primary_hue="slate")` to any Gradio-supported color name or hex code (e.g., `"blue"`, `"#FF5733"`). You can also pass custom CSS strings to the `css` parameter in `gr.Blocks` to override specific component styles.