0
# Command-Line Interface
1

2
Complete command-line interface for running uvicorn from the terminal.
3

4
## Imports
5

6
```python
7
from uvicorn.main import main
8
```
9

10
## Command Syntax
11

12
```bash
13
uvicorn [OPTIONS] APP
14
```
15

16
## Arguments
17

18
```bash
19
APP  ASGI application import string (e.g., "myapp:app")
20
```
21

22
The application can be specified as:
23
- Module and attribute: `myapp:app` (imports `app` from `myapp` module)
24
- Module and factory: `myapp:create_app` with `--factory` flag
25
- Nested attributes: `myapp.wsgi:application`
26

27
## CLI Function
28

29
```python { .api }
30
def main() -> None:
31
    """
32
    Main CLI entry point decorated with Click.
33

34
    Parses command-line arguments and runs the ASGI server.
35
    All options are passed to the run() function.
36

37
    Exit codes:
38
    - 0: Normal exit
39
    - 3: Startup failure (STARTUP_FAILURE constant)
40
    """
41
```
42

43
## Options
44

45
### Network Binding
46

47
```bash
48
--host TEXT
49
```
50
Bind socket to this host. (default: 127.0.0.1)
51

52
```bash
53
--port INTEGER
54
```
55
Bind socket to this port. (default: 8000)
56

57
```bash
58
--uds TEXT
59
```
60
Bind to Unix domain socket at this path.
61

62
```bash
63
--fd INTEGER
64
```
65
Bind to socket from this file descriptor.
66

67
### Development
68

69
```bash
70
--reload
71
```
72
Enable auto-reload on file changes. (default: disabled)
73

74
```bash
75
--reload-dir PATH
76
```
77
Set directories to watch for file changes. Can be specified multiple times. (default: current directory)
78

79
```bash
80
--reload-include TEXT
81
```
82
Set glob patterns to include for reload watching. Can be specified multiple times.
83

84
```bash
85
--reload-exclude TEXT
86
```
87
Set glob patterns to exclude from reload watching. Can be specified multiple times.
88

89
```bash
90
--reload-delay FLOAT
91
```
92
Delay in seconds between checking for file changes. (default: 0.25)
93

94
### Workers
95

96
```bash
97
--workers INTEGER
98
```
99
Number of worker processes to run. (default: 1)
100

101
### Event Loop
102

103
```bash
104
--loop [none|auto|asyncio|uvloop]
105
```
106
Event loop implementation. (default: auto)
107
- `auto`: Automatically select uvloop if available, otherwise asyncio
108
- `asyncio`: Use asyncio event loop
109
- `uvloop`: Use uvloop (requires uvloop package)
110
- `none`: No event loop configuration
111

112
### HTTP Protocol
113

114
```bash
115
--http [auto|h11|httptools]
116
```
117
HTTP protocol implementation. (default: auto)
118
- `auto`: Automatically select httptools if available, otherwise h11
119
- `h11`: Use h11 pure-Python implementation
120
- `httptools`: Use httptools (requires httptools package)
121

122
### WebSocket
123

124
```bash
125
--ws [auto|none|websockets|websockets-sansio|wsproto]
126
```
127
WebSocket protocol implementation. (default: auto)
128
- `auto`: Automatically select websockets if available
129
- `none`: Disable WebSocket support
130
- `websockets`: Use websockets library
131
- `websockets-sansio`: Use websockets sans-IO implementation
132
- `wsproto`: Use wsproto library
133

134
```bash
135
--ws-max-size INTEGER
136
```
137
Maximum WebSocket message size in bytes. (default: 16777216)
138

139
```bash
140
--ws-max-queue INTEGER
141
```
142
Maximum WebSocket message queue length. (default: 32)
143

144
```bash
145
--ws-ping-interval FLOAT
146
```
147
WebSocket ping interval in seconds. (default: 20.0)
148

149
```bash
150
--ws-ping-timeout FLOAT
151
```
152
WebSocket ping timeout in seconds. (default: 20.0)
153

154
```bash
155
--ws-per-message-deflate / --no-ws-per-message-deflate
156
```
157
Enable/disable WebSocket per-message deflate compression. (default: enabled)
158

159
### Lifespan
160

161
```bash
162
--lifespan [auto|on|off]
163
```
164
Lifespan event handling mode. (default: auto)
165
- `auto`: Enable lifespan if application supports it
166
- `on`: Force lifespan events (error if not supported)
167
- `off`: Disable lifespan events
168

169
### Interface
170

171
```bash
172
--interface [auto|asgi3|asgi2|wsgi]
173
```
174
Application interface type. (default: auto)
175
- `auto`: Automatically detect interface type
176
- `asgi3`: ASGI3 interface
177
- `asgi2`: ASGI2 interface (class-based)
178
- `wsgi`: WSGI interface
179

180
### Logging
181

182
```bash
183
--log-config PATH
184
```
185
Logging configuration file path. Supports .json, .yaml, and .ini formats.
186

187
```bash
188
--log-level [critical|error|warning|info|debug|trace]
189
```
190
Logging level. (default: info)
191

192
```bash
193
--access-log / --no-access-log
194
```
195
Enable/disable access logging. (default: enabled)
196

197
```bash
198
--use-colors / --no-use-colors
199
```
200
Enable/disable colored logging output. (default: auto-detect)
201

202
### Headers
203

204
```bash
205
--proxy-headers / --no-proxy-headers
206
```
207
Enable/disable proxy header parsing (X-Forwarded-*). (default: enabled)
208

209
```bash
210
--server-header / --no-server-header
211
```
212
Enable/disable Server header in responses. (default: enabled)
213

214
```bash
215
--date-header / --no-date-header
216
```
217
Enable/disable Date header in responses. (default: enabled)
218

219
```bash
220
--forwarded-allow-ips TEXT
221
```
222
Comma-separated list of IPs to trust for proxy headers. (default: 127.0.0.1)
223

224
```bash
225
--header TEXT
226
```
227
Add custom default header in Name:Value format. Can be specified multiple times.
228

229
### Application
230

231
```bash
232
--root-path TEXT
233
```
234
Set ASGI root_path for sub-mounted applications. (default: "")
235

236
```bash
237
--app-dir TEXT
238
```
239
Add directory to PYTHONPATH before importing application. (default: current directory)
240

241
```bash
242
--factory
243
```
244
Treat APP as a factory function that returns the application. (default: disabled)
245

246
### Performance
247

248
```bash
249
--limit-concurrency INTEGER
250
```
251
Maximum number of concurrent connections. (default: unlimited)
252

253
```bash
254
--backlog INTEGER
255
```
256
Socket listen backlog size. (default: 2048)
257

258
```bash
259
--limit-max-requests INTEGER
260
```
261
Maximum requests before worker restart. (default: unlimited)
262

263
### Timeouts
264

265
```bash
266
--timeout-keep-alive INTEGER
267
```
268
Keep-alive connection timeout in seconds. (default: 5)
269

270
```bash
271
--timeout-graceful-shutdown INTEGER
272
```
273
Graceful shutdown timeout in seconds. (default: unlimited)
274

275
```bash
276
--timeout-worker-healthcheck INTEGER
277
```
278
Worker health check timeout in seconds. (default: 5)
279

280
### SSL/TLS
281

282
```bash
283
--ssl-keyfile TEXT
284
```
285
SSL private key file path.
286

287
```bash
288
--ssl-certfile TEXT
289
```
290
SSL certificate file path.
291

292
```bash
293
--ssl-keyfile-password TEXT
294
```
295
Password for encrypted SSL private key.
296

297
```bash
298
--ssl-version INTEGER
299
```
300
SSL protocol version. (default: ssl.PROTOCOL_TLS_SERVER)
301

302
```bash
303
--ssl-cert-reqs INTEGER
304
```
305
SSL certificate requirements. (default: ssl.CERT_NONE)
306

307
```bash
308
--ssl-ca-certs TEXT
309
```
310
CA certificates file path for client verification.
311

312
```bash
313
--ssl-ciphers TEXT
314
```
315
SSL cipher configuration. (default: "TLSv1")
316

317
### Protocol-Specific
318

319
```bash
320
--h11-max-incomplete-event-size INTEGER
321
```
322
Maximum buffer size for h11 incomplete events in bytes.
323

324
```bash
325
--env-file PATH
326
```
327
Environment file (.env) to load before starting.
328

329
### Information
330

331
```bash
332
--version
333
```
334
Display uvicorn version and exit.
335

336
```bash
337
--help
338
```
339
Display help message and exit.
340

341
## Usage Examples
342

343
### Basic Usage
344

345
```bash
346
# Run application from myapp module
347
uvicorn myapp:app
348

349
# Specify host and port
350
uvicorn myapp:app --host 0.0.0.0 --port 8000
351

352
# Run on all interfaces
353
uvicorn myapp:app --host 0.0.0.0
354
```
355

356
### Development Mode
357

358
```bash
359
# Enable auto-reload
360
uvicorn myapp:app --reload
361

362
# Watch specific directories
363
uvicorn myapp:app --reload --reload-dir ./src --reload-dir ./lib
364

365
# Watch specific file patterns
366
uvicorn myapp:app --reload \
367
  --reload-include "*.py" \
368
  --reload-include "*.yaml" \
369
  --reload-exclude "*.pyc"
370

371
# Enable debug logging
372
uvicorn myapp:app --reload --log-level debug
373

374
# Enable trace logging
375
uvicorn myapp:app --reload --log-level trace
376
```
377

378
### Production Mode
379

380
```bash
381
# Run with multiple workers
382
uvicorn myapp:app --host 0.0.0.0 --port 8000 --workers 4
383

384
# Production configuration
385
uvicorn myapp:app \
386
  --host 0.0.0.0 \
387
  --port 8000 \
388
  --workers 4 \
389
  --limit-concurrency 1000 \
390
  --limit-max-requests 10000 \
391
  --timeout-keep-alive 5 \
392
  --timeout-graceful-shutdown 30 \
393
  --access-log
394

395
# Disable access logs for performance
396
uvicorn myapp:app --workers 4 --no-access-log
397
```
398

399
### SSL/TLS
400

401
```bash
402
# Enable HTTPS
403
uvicorn myapp:app \
404
  --host 0.0.0.0 \
405
  --port 443 \
406
  --ssl-keyfile /path/to/key.pem \
407
  --ssl-certfile /path/to/cert.pem
408

409
# HTTPS with client verification
410
uvicorn myapp:app \
411
  --ssl-keyfile /path/to/key.pem \
412
  --ssl-certfile /path/to/cert.pem \
413
  --ssl-ca-certs /path/to/ca.pem \
414
  --ssl-cert-reqs 2
415
```
416

417
### Unix Domain Socket
418

419
```bash
420
# Bind to Unix socket
421
uvicorn myapp:app --uds /tmp/uvicorn.sock
422

423
# Run behind Nginx with Unix socket
424
uvicorn myapp:app --uds /var/run/uvicorn.sock --workers 4
425
```
426

427
### Protocol Selection
428

429
```bash
430
# Use specific HTTP protocol
431
uvicorn myapp:app --http h11
432
uvicorn myapp:app --http httptools
433

434
# Use specific WebSocket protocol
435
uvicorn myapp:app --ws websockets
436
uvicorn myapp:app --ws wsproto
437

438
# Disable WebSocket support
439
uvicorn myapp:app --ws none
440

441
# Use specific event loop
442
uvicorn myapp:app --loop uvloop
443
```
444

445
### Custom Headers
446

447
```bash
448
# Add custom default headers
449
uvicorn myapp:app \
450
  --header "X-API-Version:1.0" \
451
  --header "X-Server:MyAPI"
452

453
# Disable standard headers
454
uvicorn myapp:app --no-server-header --no-date-header
455
```
456

457
### Proxy Configuration
458

459
```bash
460
# Trust proxy headers from localhost
461
uvicorn myapp:app --proxy-headers --forwarded-allow-ips "127.0.0.1"
462

463
# Trust multiple proxy IPs
464
uvicorn myapp:app --proxy-headers \
465
  --forwarded-allow-ips "127.0.0.1,10.0.0.1,192.168.1.1"
466

467
# Trust proxy network
468
uvicorn myapp:app --proxy-headers \
469
  --forwarded-allow-ips "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
470

471
# Disable proxy headers
472
uvicorn myapp:app --no-proxy-headers
473
```
474

475
### Application Mounting
476

477
```bash
478
# Mount application at subpath
479
uvicorn myapp:app --root-path /api/v1
480

481
# Add custom module directory
482
uvicorn myapp:app --app-dir /path/to/app
483

484
# Use factory function
485
uvicorn myapp:create_app --factory
486
```
487

488
### Logging Configuration
489

490
```bash
491
# Use custom logging config
492
uvicorn myapp:app --log-config logging.yaml
493

494
# JSON logging config
495
uvicorn myapp:app --log-config logging.json
496

497
# INI logging config
498
uvicorn myapp:app --log-config logging.ini
499

500
# Set log level
501
uvicorn myapp:app --log-level warning
502
```
503

504
### Environment Configuration
505

506
```bash
507
# Load environment file
508
uvicorn myapp:app --env-file .env
509

510
# Load production environment
511
uvicorn myapp:app --env-file .env.production
512
```
513

514
### WebSocket Configuration
515

516
```bash
517
# Configure WebSocket limits
518
uvicorn myapp:app \
519
  --ws-max-size 33554432 \
520
  --ws-max-queue 64 \
521
  --ws-ping-interval 30.0 \
522
  --ws-ping-timeout 30.0
523

524
# Disable WebSocket compression
525
uvicorn myapp:app --no-ws-per-message-deflate
526
```
527

528
### Interface Selection
529

530
```bash
531
# Run ASGI2 application
532
uvicorn myapp:App --interface asgi2
533

534
# Run WSGI application (e.g., Flask)
535
uvicorn myapp:app --interface wsgi
536

537
# Auto-detect interface
538
uvicorn myapp:app --interface auto
539
```
540

541
### Performance Tuning
542

543
```bash
544
# High-performance configuration
545
uvicorn myapp:app \
546
  --host 0.0.0.0 \
547
  --port 8000 \
548
  --workers 8 \
549
  --http httptools \
550
  --loop uvloop \
551
  --limit-concurrency 2000 \
552
  --backlog 4096 \
553
  --no-access-log
554

555
# Connection limiting
556
uvicorn myapp:app --limit-concurrency 500
557

558
# Request limiting
559
uvicorn myapp:app --limit-max-requests 50000
560
```
561

562
### Timeouts
563

564
```bash
565
# Configure timeouts
566
uvicorn myapp:app \
567
  --timeout-keep-alive 10 \
568
  --timeout-graceful-shutdown 60 \
569
  --timeout-worker-healthcheck 10
570
```
571

572
### Python Module Execution
573

574
```bash
575
# Run uvicorn as module
576
python -m uvicorn myapp:app
577

578
# With options
579
python -m uvicorn myapp:app --host 0.0.0.0 --port 8000 --reload
580
```
581

582
### Lifespan Control
583

584
```bash
585
# Force lifespan events
586
uvicorn myapp:app --lifespan on
587

588
# Disable lifespan events
589
uvicorn myapp:app --lifespan off
590

591
# Auto-detect lifespan support
592
uvicorn myapp:app --lifespan auto
593
```
594

595
### Complete Production Example
596

597
```bash
598
uvicorn myapp:app \
599
  --host 0.0.0.0 \
600
  --port 8000 \
601
  --workers 4 \
602
  --loop uvloop \
603
  --http httptools \
604
  --ws websockets \
605
  --proxy-headers \
606
  --forwarded-allow-ips "10.0.0.0/8" \
607
  --limit-concurrency 1000 \
608
  --backlog 2048 \
609
  --limit-max-requests 100000 \
610
  --timeout-keep-alive 5 \
611
  --timeout-graceful-shutdown 30 \
612
  --timeout-worker-healthcheck 10 \
613
  --access-log \
614
  --log-level info \
615
  --no-use-colors
616
```
617

618
### Complete Development Example
619

620
```bash
621
uvicorn myapp:app \
622
  --host 127.0.0.1 \
623
  --port 8000 \
624
  --reload \
625
  --reload-dir ./src \
626
  --reload-include "*.py" \
627
  --reload-include "*.yaml" \
628
  --reload-exclude "*.pyc" \
629
  --reload-exclude "__pycache__/*" \
630
  --log-level debug \
631
  --use-colors \
632
  --access-log
633
```
634

635
## Environment Variables
636

637
Uvicorn CLI also respects environment variables for configuration when using an env-file:
638

639
```bash
640
# .env file
641
HOST=0.0.0.0
642
PORT=8000
643
WORKERS=4
644
LOG_LEVEL=info
645
RELOAD=false
646
```
647

648
```bash
649
# Load from env file
650
uvicorn myapp:app --env-file .env
651
```
652

653
## Exit Codes
654

655
- `0`: Normal exit (server shutdown gracefully)
656
- `3`: Startup failure (application failed to start)
657

658
## Version Information
659

660
```bash
661
# Show version
662
uvicorn --version
663

664
# Output format:
665
# Running uvicorn 0.37.0 with CPython 3.11.0 on Linux
666
```
667

668
## Help Information
669

670
```bash
671
# Show help
672
uvicorn --help
673

674
# Show detailed help for all options
675
uvicorn --help
676
```
677

678
## Running with Gunicorn
679

680
Uvicorn can also be used as a Gunicorn worker (deprecated, use uvicorn-worker package instead):
681

682
```bash
683
gunicorn myapp:app -w 4 -k uvicorn.workers.UvicornWorker
684
```
685

686
## Docker Usage
687

688
```bash
689
# Dockerfile
690
FROM python:3.11
691
WORKDIR /app
692
COPY . .
693
RUN pip install uvicorn[standard]
694
CMD ["uvicorn", "myapp:app", "--host", "0.0.0.0", "--port", "8000"]
695
```
696

697
```bash
698
# Build and run
699
docker build -t myapp .
700
docker run -p 8000:8000 myapp
701
```
702

703
## Systemd Service
704

705
```ini
706
# /etc/systemd/system/uvicorn.service
707
[Unit]
708
Description=Uvicorn ASGI Server
709
After=network.target
710

711
[Service]
712
Type=simple
713
User=www-data
714
WorkingDirectory=/var/www/myapp
715
ExecStart=/usr/local/bin/uvicorn myapp:app \
716
  --host 0.0.0.0 \
717
  --port 8000 \
718
  --workers 4
719
Restart=always
720

721
[Install]
722
WantedBy=multi-user.target
723
```
724

725
```bash
726
# Enable and start service
727
sudo systemctl enable uvicorn
728
sudo systemctl start uvicorn
729
```
730