# How to Run the MediaCrawler WebUI for Non-Command-Line Usage

> Easily run the MediaCrawler WebUI without the command line. Launch the graphical interface via development mode or build static assets for production deployment.

- Repository: [程序员阿江-Relakkes/MediaCrawler](https://github.com/NanmiCoder/MediaCrawler)
- Tags: how-to-guide
- Published: 2026-08-14

---

**Launch MediaCrawler's graphical interface by running the FastAPI backend and Vite frontend in development mode, or build static assets for a single-process production deployment.**

MediaCrawler provides a **WebUI interface** that eliminates the need for terminal commands when configuring and monitoring crawling jobs. Built on a FastAPI backend and Vite-powered frontend, this browser-based dashboard lets you set parameters, track progress, and export results through interactive forms. According to the NanmiCoder/MediaCrawler source code, the WebUI supports two distinct running modes tailored to different deployment scenarios.

## Prerequisites for Running the WebUI

Before starting the graphical interface, verify these dependencies:

- **uv** – the recommended Python package manager for dependency resolution
- **Node.js** (≥ 16) – required for the Vite development server and static builds
- **Playwright browsers** (optional) – only needed if you disable CDP mode

Install and verify uv:

```bash
uv --version   # should show a version number

```

Install browser drivers if needed:

```bash
uv run playwright install

```

Clone the repository and sync Python dependencies:

```bash
git clone https://github.com/NanmiCoder/MediaCrawler.git
cd MediaCrawler
uv sync

```

## Development Mode: Interactive WebUI with Hot Reloading

**Development mode** runs the API server and Vite dev server as separate processes. This provides instant code reloading and is ideal for exploring features or customizing the interface.

### Start the FastAPI Backend

In [`api/main.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/api/main.py), the FastAPI application registers routers for crawler operations, data retrieval, and WebSocket connections. Launch the backend on port 8080:

```bash

# Terminal 1

uv run uvicorn api.main:app --port 8080 --reload

```

The `--reload` flag enables automatic restart when Python files change. The API server exposes endpoints at `http://localhost:8080/api/`.

### Start the Vite Frontend Dev Server

The frontend source lives in `webui/` and proxies API requests to the backend. Open a second terminal:

```bash

# Terminal 2

cd webui
npm install
npm run dev

```

By default, the dev server serves the WebUI at `http://localhost:5173` and forwards `/api` calls to port 8080.

### Access the WebUI Interface

Open **http://localhost:5173** in your browser. The dashboard automatically connects to the backend and displays:

- Platform selection (Xiaohongshu, Bilibili, etc.)
- Login type configuration (QR code, phone)
- Crawler type and keyword input
- Real-time progress monitoring via WebSocket

## Production Mode: Single-Process WebUI Deployment

**Production mode** bundles the frontend into static assets served directly by the FastAPI process. No Node.js runtime is required for operation.

### Build Static Frontend Assets

Execute the build command once to compile the Vite project:

```bash
cd webui
npm install
npm run build

```

Output is written to `api/webui/`, as configured in the build pipeline (documented in README lines 98–104).

### Run the Unified API Server

Start only the FastAPI backend—it automatically detects and mounts the built assets:

```bash
uv run uvicorn api.main:app --port 8080

```

In [`api/main.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/api/main.py) (lines 91–102), the static file mounting logic checks for `WEBUI_DIR` and registers routes for `/assets`, `/logos`, and `/static`. The compiled UI is served at the root path `/`.

Access **http://localhost:8080** to use the WebUI without any separate frontend process.

## Verifying Your WebUI Environment

Confirm that all dependencies are correctly installed by calling the environment check endpoint:

```bash
curl http://localhost:8080/api/env/check

```

A successful response returns `"success": true`. This endpoint, implemented in [`api/main.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/api/main.py) (lines 88–130), executes `uv run main.py --help` to validate the crawling engine's availability.

## Architecture of the MediaCrawler WebUI

| Component | Path | Function |
|-----------|------|----------|
| **FastAPI backend** | [`api/main.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/api/main.py) | HTTP server, router registration, static file serving |
| **Crawler router** | [`api/routers/crawler.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/api/routers/crawler.py) | Handles `/api/crawler/*` endpoints for job submission |
| **WebUI source** | `webui/` | Vite + Vue/React frontend code |
| **Crawling engine** | [`main.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/main.py) (project root) | CLI entry point invoked by API routes |
| **Configuration** | [`config/base_config.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/config/base_config.py) | Global toggles affecting UI-driven behavior |

When you submit a crawl job through the WebUI, the frontend sends a POST request to `/api/crawler/run`:

```json
POST /api/crawler/run
{
  "platform": "xhs",
  "login_type": "qrcode",
  "crawler_type": "search",
  "keyword": "AI",
  "save_option": "jsonl"
}

```

The backend translates this JSON into command-line arguments and executes [`main.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/main.py) with the specified parameters.

## One-Line Launch Commands

### Background Development Mode

```bash
uv run uvicorn api.main:app --port 8080 --reload & \
  cd webui && npm install && npm run dev

```

### Complete Production Deployment

```bash
cd webui && npm install && npm run build && \
  cd .. && uv run uvicorn api.main:app --port 8080

```

## Key Differences Between WebUI Modes

| Aspect | Development Mode | Production Mode |
|--------|---------------|-----------------|
| **Processes** | Two (API + Node dev server) | One (API only) |
| **Access URL** | `http://localhost:5173` | `http://localhost:8080` |
| **Code changes** | Instant hot reload | Requires rebuild |
| **Deployment complexity** | Higher | Lower |
| **Best for** | Exploration, customization | Stable operation, server deployment |

## Summary

- **MediaCrawler's WebUI** provides full graphical control over crawling operations without terminal interaction.
- **Development mode** (`uv run uvicorn api.main:app --reload` + `npm run dev`) offers the fastest feedback loop for interactive use.
- **Production mode** (`npm run build` then single API server) simplifies deployment by eliminating the Node dependency.
- The **backend** ([`api/main.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/api/main.py)) serves both API endpoints and—when assets are built—static UI files.
- The **frontend** (`webui/`) communicates with `/api` routes that invoke the core crawling engine in [`main.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/main.py).

## Frequently Asked Questions

### Can I run the WebUI without installing Node.js permanently?

No for development mode—Node.js is required to run the Vite dev server. Yes for production mode—Node is only needed during the build step. After running `npm run build`, you can deploy using only Python and uv.

### Why does the WebUI use port 5173 in development but 8080 in production?

The Vite dev server defaults to port 5173 with proxy configuration to reach the API at 8080. In production, the FastAPI server itself serves the UI at port 8080, consolidating access to a single endpoint.

### How do I debug WebUI connectivity issues?

Check three layers: (1) Verify the API responds with `curl http://localhost:8080/api/env/check`, (2) confirm the frontend proxy configuration in [`webui/vite.config.js`](https://github.com/NanmiCoder/MediaCrawler/blob/main/webui/vite.config.js) points to the correct backend port, and (3) inspect browser DevTools Network tab for failed `/api` requests.

### Can I customize which platforms appear in the WebUI interface?

Platform options are populated from the API response and ultimately derive from the modules in [`main.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/main.py). To add or remove platforms, modify the crawler registration logic in [`api/routers/crawler.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/api/routers/crawler.py) and ensure corresponding platform handlers exist in the crawling engine.