CadQuery Web Viewer

Preview CadQuery or build123d models in your browser and refresh the view while you edit Python — without manually exporting meshes each time.

Try it live →

Place a screenshot or short GIF of the running viewer at assets/screenshot.png. The image is referenced here so the README renders the hero once committed; until then GitHub will show a broken image. Open an issue if you'd like a starting screenshot grabbed from the live demo.

What you get

• Browser viewer for 3D models: orbit, zoom, measurements, clipping, transparency, and related viewing tools.
• glTF 2.0 / GLB — a standard mesh format many 3D tools understand. The UI is built around the web model-viewer component, so you get common material and lighting behavior in the browser.
• Live updates while you change geometry in Python (the app keeps a channel open so the page can refresh when you publish again).
• Optional disk cache for uploaded GLBs when you run the long-lived server — see Usage.

The API and packaging are meant to be a mostly drop-in replacement for Yet Another CAD Viewer (YACV). Package renames and choosing how Python talks to the viewer — embedded server, separate server process, or buffer-only (server_type) — are covered in Migrating from yacv-server / yacv-viewer; project history and upstream links are in Special thanks at the end of this file.

Table of contents

• Quick start
• What you get
• Documentation
• Examples in this repo
• Trust model
• Contributing
• Special thanks

Quick start

Requires Python 3.10 through 3.12 (see requires-python in pyproject.toml). The upstream vtk==9.3.1 pin that previously blocked Python 3.13 is gone — build123d>=0.11 depends on cadquery-ocp-novtk 7.9.x, which ships cp313/cp314 wheels — so widening the range is now a matter of testing rather than an upstream blocker.

Install with pip

The viewer package depends on build123d. The example below uses CadQuery, which is a separate install:

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install cadquery-web-viewer cadquery

While the venv is active, run cadquery-web-viewer or python -m cadquery_web_viewer.

Other install methods (pipx, uv tool, Docker): docs/install.md.

Preview a CadQuery box locally

The library starts a small local server and a browser tab. By default the process waits until you close the viewer tab, so short scripts do not exit before you inspect the model.

import cadquery as cq

from cadquery_web_viewer import show

box = cq.Workplane().box(10, 10, 10)
show(box)

More options (host, port, timeouts, multiple show() calls): docs/usage.md.

Same box with a remote server

In one terminal, keep the viewer running:

cadquery-web-viewer --host localhost --port 32323

In another terminal, with the same Python environment:

import cadquery as cq

from cadquery_web_viewer import show

box = cq.Workplane().box(10, 10, 10)
show(
    box,
    server_type="remote",
    remote_options={"host": "localhost", "port": 32323},
)

Documentation

• Installation — pipx, uv tool, Docker, and other install paths
• Usage — long-lived server, cache, show() options
• HTTP API — Flask /api endpoints (SSE, GLB upload, static UI), trust model
• Migrating from YACV
• Development
• Changelog

Examples in this repo

Trust model

cadquery-web-viewer is intended for localhost or trusted networks only:

• The HTTP API serves CORS Access-Control-Allow-Origin: *, so any origin may call it from a browser.
• PUT /api/object/<name> accepts a JSON body with a url field and the server fetches that URL (up to 50 MB) over http/https.
• The Python runtime is plain flask.Flask.run — there is no auth, rate limiting, or TLS.

For details and operational guidance, see SECURITY.md and the Trust model section of docs/api.md.

Contributing

See CONTRIBUTING.md for the dev loop, test/lint/typecheck commands, and PR conventions. Bug reports and feature requests are welcome on the issue tracker.

Special thanks

Yet Another CAD Viewer (YACV) by Yeicor and contributors is the original project: a web-based CAD and GLB viewer with a Python backend for live tessellation, hot reload, and static export. This repository is a hard fork, with credit to the original authors.

MIT License. Third-party notices: assets/licenses.txt.