Migrate from Uvicorn

Switch from Uvicorn to Pounce with minimal changes

2 min read 493 words

Overview

If you're running an ASGI app with Uvicorn today, switching to Pounce is straightforward. The CLI syntax and configuration concepts are similar.

CLI Comparison

# Uvicorn
uvicorn myapp:app --host 0.0.0.0 --port 8000 --workers 4 --reload

# Pounce
pounce serve --app myapp:app --host 0.0.0.0 --port 8000 --workers 4 --reload

Flag Mapping

Uvicorn Flag Pounce Equivalent Notes
--host --host Same
--port --port Same
--workers --workers Pounce uses threads on 3.14t
--reload --reload Built-in, no watchfiles needed
--log-level --log-level Same levels
--ssl-certfile --ssl-certfile Same
--ssl-keyfile --ssl-keyfile Same
--root-path --root-path Same
--no-access-log --no-access-log Same
--factory (automatic) Usemyapp:create_app()syntax
--http h11 (default) h11 is the default backend
--http httptools (not needed) Built-in fast parser handles this
--ws websockets bengal-pounce[ws] Uses wsproto instead
--h11-max-incomplete-event-size ServerConfig(h11_max_incomplete_event_size=...) Programmatic only (no CLI flag)

Programmatic Comparison

# Uvicorn
import uvicorn
uvicorn.run("myapp:app", host="0.0.0.0", port=8000, workers=4)

# Pounce
import pounce
pounce.run("myapp:app", host="0.0.0.0", port=8000, workers=4)

Key Differences

Worker model

Pounce uses threads on Python 3.14t. In that runtime mode, this means:

  • Lower memory — One copy of the app instead of N
  • Shared state — Frozen config is shared, not duplicated
  • No fork — No copy-on-write, no IPC overhead

On a standard GIL build, Pounce instead uses forked process workers. Keep pre-fork application state fork-safe, initialize process-local resources in pounce.worker.startup, or choose --workers 1. See Workers before migrating a launcher that creates threads, executors, locks, or connection pools before server startup.

Compression

Pounce includes built-in compression (zstd + gzip). Uvicorn does not — you'd typically handle this in middleware or a reverse proxy.

Server-Timing

Pounce can injectServer-Timing headers automatically (--server-timing). Uvicorn has no equivalent.

HTTP/2

Pounce supports HTTP/2 viabengal-pounce[h2]. Uvicorn does not support HTTP/2.

Migration Steps

  1. 1

    Install Pounce

    uv add bengal-pounce
  2. 2

    Replace the run command

    # Before
uvicorn myapp:app --host 0.0.0.0 --workers 4

# After
pounce serve --app myapp:app --host 0.0.0.0 --workers 4
  3. 3

    Update Dockerfile / systemd

    Update deployment configs if applicable.

  4. 4

    Test your application

    Pounce serves standard ASGI, so any compliant app works without code changes.

Verify Migration

Migration Verification

0/4 complete
  • Pounce installed (pounce --helpworks)
  • Run command replaced (uvicorn → pounce)
  • Dockerfile / systemd updated if applicable
  • Application tested and serving correctly

See Also