uWSGI Server

Warnings

• gotcha Installing `uwsgi` via `pip` often fails without system-level build tools (C compiler, Python development headers). This is because uWSGI is a C application that gets compiled during installation.
  Fix: Ensure `build-essential` (Debian/Ubuntu) or `Development Tools` (Fedora/RHEL) and `python-dev`/`python-devel` are installed on your system. Alternatively, consider using `pyuwsgi` which provides pre-built wheels and includes common libraries.
• gotcha Python threads are disabled by default within uWSGI's Python plugin. Application-generated threads will not run unless explicitly enabled.
  Fix: Enable Python threads by adding `--enable-threads` (command line) or `enable-threads = true` (configuration file) to your uWSGI configuration. Running in multithreading mode (with `threads` option) automatically enables it.
• breaking Never expose a socket speaking the native `uwsgi` protocol directly to the public network, as it allows dynamic loading of applications (arbitrary code execution).
  Fix: Always place a reverse proxy (like Nginx or Apache) in front of uWSGI instances to sanitize/validate requests and proxy them using the `uwsgi` protocol.
• gotcha If an HTTP request contains a body (e.g., POST request from a form), your application *must* read (consume) the entire body. Failure to do so can 'clobber' the communication socket with the web server, leading to hung connections or errors.
  Fix: Ensure your WSGI application or framework fully reads the request `wsgi.input` stream when a request body is expected.
• gotcha When using UNIX sockets, they are filesystem objects subject to standard UNIX permissions. If your web server lacks write access, it cannot communicate with uWSGI.
  Fix: Set appropriate permissions for the UNIX socket using the `--chmod-socket` option (e.g., `--chmod-socket=666` or specific user/group permissions) so your web server can access it.
• gotcha Receiving 'invalid request block size' errors in logs often indicates that the default internal buffer size (4096 bytes) for request headers is too small.
  Fix: Increase the buffer size with the `--buffer-size` option (e.g., `--buffer-size 8192`) up to 65535 bytes, based on your application's needs.
• gotcha Running uWSGI instances directly as the `root` user is a security risk.
  Fix: Start uWSGI as `root` if necessary for binding to privileged ports, but immediately drop privileges to a non-root user and group using the `uid` and `gid` options.

Install

• pip install uwsgi Install latest stable release

Imports

• uwsgi

  import uwsgi

  The `uwsgi` module is automatically injected into Python applications *only when they are run by the uWSGI server*. It provides access to server configuration, internal functions, and statistics. Attempting to import it outside of a uWSGI context will raise an ImportError.

Quickstart

This quickstart demonstrates how to create a basic WSGI 'Hello World' application and run it using the `uwsgi` command-line tool. The `--http` option binds to an HTTP port, `--wsgi-file` specifies your application file, `--callable` points to the WSGI callable, and `--processes`/`--threads` configure concurrency.

import os

def application(environ, start_response):
    status = '200 OK'
    headers = [('Content-type', 'text/plain')]
    start_response(status, headers)
    return [b"Hello from uWSGI and Python!"]

# To run: save this as `wsgi_app.py`
# Then execute from your terminal:
# uwsgi --http :9090 --wsgi-file wsgi_app.py --callable application --processes 1 --threads 1