Install & Compatibility
Where this runs
tested against v1.8.11 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.198s · 18.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.178s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Request
✓ from webob import Request
Response
✓ from webob import Response
HTTPNotFound
✓ from webob.exc import HTTPNotFound
Common HTTP exceptions are available under webob.exc
This quickstart demonstrates a minimal WSGI application using WebOb. It handles incoming requests, creates a Response object, and serves a simple 'Hello, WebOb!' page for the root path or a 'Not Found' error for other paths. The example includes a basic `wsgiref` server for local execution.
from webob import Request, Response
def application(environ, start_response):
request = Request(environ)
response = Response()
if request.path == '/':
response.status = '200 OK'
response.content_type = 'text/html'
response.text = '<h1>Hello, WebOb!</h1>'
else:
response.status = '404 Not Found'
response.content_type = 'text/plain'
response.text = 'Not Found'
return response(environ, start_response)
# Example of how to 'run' a request for testing (not a full WSGI server)
if __name__ == '__main__':
from wsgiref.simple_server import make_server
httpd = make_server('', 8000, application)
print('Serving on http://localhost:8000')
httpd.serve_forever()
Debug
Known issues
breakingThe `Response.set_cookie` method's `key` parameter was renamed to `name`. Using `key` was deprecated in WebOb 1.5 and completely removed in 1.7.fixUpdate calls to `response.set_cookie(key=...)` to `response.set_cookie(name=...)`.
affects: >=1.7
breakingSetting a text `body` without explicitly specifying a `charset` in `Response` objects will raise a `TypeError` since WebOb 1.7. Previously, it might have silently defaulted.fixFor text content, either provide `charset='UTF-8'` (or another suitable encoding) in the `Response` constructor, or use the `text` parameter instead of `body` (e.g., `Response(text='content')`).
affects: >=1.7
breakingThe `status` attribute of a `Response` object no longer accepts arbitrary strings (like `None None`) and now strictly requires a format matching `<integer status code> <explanation of status code>`. Invalid strings will raise a `ValueError`.fixEnsure `response.status` is set to a valid HTTP status string (e.g., `'200 OK'`, `'404 Not Found'`).
affects: >=1.5, <1.7 (deprecation), >=1.7 (breaking change)
breakingWebOb 1.8.0 introduced significant changes to Accept header handling (Accept, Accept-Charset, Accept-Encoding, Accept-Language), potentially breaking applications relying on previous parsing behaviors.fixReview and test existing code that relies on WebOb's Accept header parsing after upgrading to 1.8.0 or later. Refer to the official documentation for the new behavior.
affects: >=1.8.0
securityA security vulnerability (CVE-2024-42353) in WebOb 1.8.8 and earlier can lead to an open redirect if `Response` objects are used to redirect to an unvalidated `Location` header, which is not a full URI.fixUpgrade to WebOb 1.8.9 or later. Always validate user-provided redirect URLs to ensure they are full, absolute URIs and point to trusted domains before using them in `Response.location` or `Response.status = '302 Found'; response.headers['Location'] = ...`.
affects: <1.8.9
gotchaThe `SameSite` cookie attribute's 'None' value was introduced in WebOb 1.8.6. While WebOb doesn't enable `SameSite` by default, older clients may be incompatible with this new value, leading to unexpected cookie behavior.fixIf explicitly setting `SameSite=None`, be aware of potential client incompatibilities. Consider the implications for older browser versions. Validation of `SameSite` values can be disabled via a module flag if needed for specific scenarios.
affects: >=1.8.6
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'webob'
The `webob` library has not been installed in your Python environment, or the environment where the code is being run does not have `webob` accessible.
fixInstall the library using pip: `pip install webob`
AttributeError: 'Request' object has no attribute 'get_json'
Developers often expect methods like `get_json()` or `get_data()` for request body parsing (common in frameworks like Flask or Django), but WebOb uses properties like `request.json` (for JSON bodies) or `request.body` (for raw bytes).
fixUse `request.json` to automatically parse a JSON body (if `Content-Type` is `application/json`), or `request.body` to get the raw request body as bytes.
TypeError: a bytes-like object is required, not 'dict'
The `webob.Response.body` attribute expects a `bytes` object (or something convertible to it), but you attempted to assign a dictionary, list, or another non-bytes/non-string object directly.
fixConvert the object to a string (e.g., by serializing to JSON) and then encode it to bytes (e.g., `response.body = json.dumps(data).encode('utf-8')`), or use `response.json` for automatic JSON serialization. ValueError: No JSON object could be decoded
This error occurs when accessing `request.json`, but the request's `Content-Type` header is not `application/json`, or the request body is not a valid JSON string, preventing WebOb from successfully parsing it.
fixEnsure the client sends `Content-Type: application/json` and a valid JSON payload. Alternatively, check the `Content-Type` and manually parse `request.body` using Python's `json` module if needed.
TypeError: View returned None -- it must return a Response instance, a string, or a bytes object (or an iterable of bytes)
The `@webob.dec.wsgify` decorator expects the decorated function to return a `webob.Response` instance, a string, or bytes (or an iterable of bytes) that it can convert into a response. Returning `None` or an incompatible type (like a dict) will cause this error.
fixEnsure the decorated function explicitly returns a `webob.Response` object, a string, or a bytes object.
Upgrade
Version history
1.8.11latest on PyPI · released Aug 2, 2026
Audit
Dependencies
legacy-cgirequiredRequired for Python 3.13 compatibility.