gunicorn "error: unrecognized arguments" (--host, --port, --worker) (tested)

gunicorn: error: unrecognized arguments: --host 0.0.0.0 (or --port 8000) means you passed a uvicorn/Flask-style flag; gunicorn takes --bind 0.0.0.0:8000. Below: that error and two look-alikes, reproduced, with the corrected command.

1. Reproduce

A minimal WSGI app (app.py):

def app(environ, start_response):
    start_response('200 OK', [('Content-Type', 'text/plain')]); return [b'ok']

b1.sh starts it with flags people carry over from uvicorn, Flask or Django, plus two look-alikes:

# uvicorn/flask-style flags that gunicorn does not have, and a few look-alikes
for args in "app:app --host 0.0.0.0" "app:app --port 8000" "app:app --worker 4" \
            "app:app --timeout 60s" "app:app --bind 0.0.0.0:8000 --workers 4 --timeout 60 --check-config"; do
  echo "\$ gunicorn $args"
  gunicorn $args > out.txt 2>&1; rc=$?; tail -1 out.txt; echo "  exit $rc"
done

Output (gunicorn 26.2.0, Python 3.13):

$ gunicorn app:app --host 0.0.0.0
gunicorn: error: unrecognized arguments: --host 0.0.0.0
  exit 2
$ gunicorn app:app --port 8000
gunicorn: error: unrecognized arguments: --port 8000
  exit 2
$ gunicorn app:app --worker 4
gunicorn: error: ambiguous option: --worker could match --workers, --worker-class, --worker-connections, --worker-tmp-dir
  exit 2
$ gunicorn app:app --timeout 60s
gunicorn: error: argument -t/--timeout: invalid int value: '60s'
  exit 2
$ gunicorn app:app --bind 0.0.0.0:8000 --workers 4 --timeout 60 --check-config
  exit 0

2. What each error means

• unrecognized arguments: --host 0.0.0.0 / --port 8000: gunicorn has no --host or --port (those are uvicorn / flask run / manage.py runserver options). Address and port go together in --bind HOST:PORT (short -b).
• ambiguous option: --worker could match --workers, --worker-class, ...: the option is --workers (or -w).
• argument -t/--timeout: invalid int value: '60s': timeouts are plain seconds, --timeout 60.
• All of them exit with status 2 before any worker starts. The corrected command passes --check-config silently with exit 0, a quick way to validate flags in CI or a Dockerfile.

3. Fix

Translate the flags: --host 0.0.0.0 --port 8000 becomes --bind 0.0.0.0:8000, --worker 4 becomes --workers 4, --timeout 60s becomes --timeout 60.

Related: gunicorn WORKER TIMEOUT, where gunicorn logs go.

Written with AI assistance. Measured on 2026-10-23 with gunicorn 26.2.0 and Python 3.13 on Linux. The script ran verbatim and the output was pasted unedited. PlainTables is our extension; gunicorn is free.