Registry / http-networking / python-multipart

python-multipart

JSON →
library0.0.32pypypi✓ verified 27d ago

python-multipart is an Apache2-licensed streaming multipart parser for Python. It is designed for handling `multipart/form-data` POST requests, typically used in web servers for file uploads and complex form data. The library is actively maintained with frequent releases, currently at version 0.0.22, and supports modern Python versions (>=3.10).

pip install python-multipart
INSTALL
IMPORT
SIG · PYTHON-MULTIPART
P
python-multipart
http-networkingpythonv0.0.32
Install
1.6s avg
Import
51ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.0.32 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.056s · 18MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.046s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MultipartParser
from python_multipart import MultipartParser
import multipart
The package to install is `python-multipart`, but the module to import is `python_multipart`. The old import path `import multipart` was changed in version 0.0.13 and conflicts with a separate, different PyPI package named `multipart`.

This quickstart demonstrates how to parse a `multipart/form-data` request body using `MultipartParser`. It simulates an incoming HTTP request with form fields and a file, processing them using event-like iteration.

import io from python_multipart import MultipartParser # Simulate an HTTP request body with multipart/form-data boundary = b"----WebKitFormBoundary7MA4YWxkTrZu0gW" body_data = ( b"--" + boundary + b"\r\n" b'Content-Disposition: form-data; name="username"\r\n' b'\r\n' b'testuser\r\n' b"--" + boundary + b"\r\n" b'Content-Disposition: form-data; name="upload_file"; filename="hello.txt"\r\n' b'Content-Type: text/plain\r\n' b'\r\n' b'Hello, World!\nThis is a test file.\r\n' b"--" + boundary + b"--\r\n" ) # Simulate HTTP headers headers = { "Content-Type": f"multipart/form-data; boundary={boundary.decode()}", "Content-Length": str(len(body_data)), } # Use BytesIO to simulate a file-like object for the body stream body_stream = io.BytesIO(body_data) # Create a parser instance parser = MultipartParser(headers) # Iterate through parts and process them print("Parsing multipart data:") for part in parser.parse(body_stream): if hasattr(part, 'field_name'): # It's a form field print(f" Field: name={part.field_name.decode()}, value={part.value.decode()}") elif hasattr(part, 'file_name'): # It's an uploaded file print(f" File: name={part.field_name.decode()}, filename={part.file_name.decode()}, content_type={part.content_type.decode()}") file_content = part.value # The file content is available as bytes print(f" File content length: {len(file_content)} bytes") # In a real application, you would typically save or process file_content print("\nParsing complete.")
Debug
Known issues
breakingThe import name was changed from `multipart` to `python_multipart` in version 0.0.13. Direct imports using `import multipart` will no longer work and may lead to `ModuleNotFoundError` or unexpected behavior if another `multipart` package is installed. Versions 0.0.13 and 0.0.14 were temporarily yanked due to breakage related to this change.
fix
Update all import statements from `import multipart` or `from multipart import ...` to `from python_multipart import ...`.
affects: >=0.0.13
breakingSupport for Python 3.8 and 3.9 was dropped in version 0.0.21. The library now requires Python 3.10 or newer.
fix
Upgrade your Python environment to 3.10 or a newer supported version (e.g., 3.11, 3.12, 3.13, 3.14).
affects: >=0.0.21
gotchaA separate, unrelated package on PyPI is also named `multipart`. Installing `pip install multipart` instead of `pip install python-multipart` will install the wrong library, leading to `ModuleNotFoundError` if `from python_multipart import ...` is used, or unexpected behavior if `import multipart` is still in your code.
fix
Always use `pip install python-multipart` to ensure the correct library is installed.
affects: All versions
gotchaIn version 0.0.22, the `File` object produced by the parser will no longer include directory paths in its `filename` attribute. It will only contain the base filename.
fix
If your application relied on `File.filename` containing a path, adjust your logic to expect only the base name. If paths are critical, you may need to implement custom logic to extract them from the `Content-Disposition` header directly (if present and needed).
affects: >=0.0.22
gotchaVersion 0.0.18 introduced a 'hard break' if data is found after the last boundary in `MultipartParser`. This means the parser will now strictly enforce the end of the multipart body, potentially raising errors for malformed requests that previously might have been partially processed.
fix
Ensure that clients sending multipart data adhere strictly to the `multipart/form-data` specification, particularly regarding the final boundary and any subsequent data.
affects: >=0.0.18
deprecatedIn version 0.0.15, `FutureWarning` messages were replaced with `PendingDeprecationWarning`. While not a breaking change, it indicates that certain behaviors or features are slated for deprecation or removal in future major releases.
fix
Monitor the project's changelog and documentation for details on upcoming deprecations. Address any `PendingDeprecationWarning` messages in your code to prepare for future breaking changes.
affects: >=0.0.15
gotchaThe `TypeError: can't concat dict to bytes` when initializing `MultipartParser` indicates that a dictionary of HTTP headers (or any dict) was passed as the `content_type` argument. The `MultipartParser` constructor expects the raw value of the `Content-Type` header (a string or bytes) from which it can extract the boundary, or directly the boundary string/bytes, not the entire headers dictionary.
fix
Instead of passing a dictionary of headers, extract the `Content-Type` header value (e.g., `headers.get('Content-Type')`) and pass that string or bytes object to `MultipartParser`. For example, `parser = MultipartParser(headers.get('Content-Type').encode('latin-1'))` if your headers are strings, or `parser = MultipartParser(headers.get(b'Content-Type'))` if your headers are bytes (assuming keys are bytes).
affects: All versions
Errors
Common errors & fixes
ImportError: 'python-multipart' must be installed to handle file uploads
This error occurs when a web framework (like FastAPI or Starlette) attempts to process `multipart/form-data` requests but the `python-multipart` library, which it depends on for this functionality, is not installed.
fix
pip install python-multipart
ModuleNotFoundError: No module named 'python_multipart'
The user is attempting to import the library using its PyPI distribution name (`python-multipart` converted to `python_multipart`), but the actual Python package name for import is `multipart`.
fix
import multipart
ValueError: No boundary found
This error indicates that the `multipart/form-data` parser could not find the expected boundary string in the request body, often due to a missing or incorrect `Content-Type` header or malformed multipart data.
fix
Ensure the `Content-Type` header is set correctly (e.g., `multipart/form-data; boundary=your_boundary_string`) and matches the boundary string present in the request body.
RuntimeWarning: coroutine 'MultipartReader.read_part' was never awaited
This warning appears when an asynchronous method, such as `MultipartReader.read_part()`, is called but its returned coroutine object is not awaited, meaning the asynchronous operation is never actually executed.
fix
When working with the asynchronous `multipart.reader.MultipartReader`, ensure that all calls to its async methods (e.g., `read_part`, `next_part`) are prefixed with `await` within an `async` function.
Install Issues
1 verified issue
TypeError: can't concat _io.BytesIO to bytesAll platforms · python-multipart 0.0.6+
Upgrade
Version history
0.0.32latest on PyPI · released Jun 4, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
Agent activity
76 hits · last 30 days
node
71
OpenAI (training)
1
Resources