Skip to main content

Python-Multipart

CI PyPI Python versions Discord

Python-Multipart reads the data that a web browser sends when someone submits a form or uploads a file.

pip install python-multipart

It powers file uploads in Starlette and FastAPI.

What problem does it solve?

A form sends data

When you fill in a form on a website and click "Submit", your browser sends the data to a server. The server is a program, maybe written in Python, that has to read that data and make sense of it.

Files need a special format

A form with only text, like a username, is sent as one short line: username=alice.

A form with a file is different. A file can contain anything, even text that looks like username=alice. So the browser uses a format called multipart/form-data. It splits the request into parts, one per form field, separated by a boundary: a marker string the browser picks.

This is what the server receives when you send a username and a file called cat.txt:

--boundary
Content-Disposition: form-data; name="username"

alice
--boundary
Content-Disposition: form-data; name="avatar"; filename="cat.txt"
Content-Type: text/plain

meow
--boundary--

Each part has some headers (the field name, the file name) and then the content. Every line ends with \r\n (a carriage return and a newline), which is why the examples below write \r\n explicitly. A parser is the code that turns this text back into fields and files. Python-Multipart is that parser.

Big files do not fit in memory

An upload can be a 5 GB video. If the server reads the whole request before it starts working, it needs 5 GB of memory, per upload.

Python-Multipart is a streaming parser. You give it the request a small piece (a chunk) at a time, and it tells you what it found as soon as it finds it. The full request never has to be in memory.

Usage

Parse a whole form

from io import BytesIO

from python_multipart import parse_form

body = (
    b"--boundary\r\n"
    b'Content-Disposition: form-data; name="username"\r\n'
    b"\r\n"
    b"alice\r\n"
    b"--boundary\r\n"
    b'Content-Disposition: form-data; name="avatar"; filename="cat.txt"\r\n'
    b"Content-Type: text/plain\r\n"
    b"\r\n"
    b"meow\r\n"
    b"--boundary--\r\n"
)
headers = {"Content-Type": "multipart/form-data; boundary=boundary"}


def on_field(field):
    print("Field:", field.field_name, "=", field.value)


def on_file(file):
    file.file_object.seek(0)
    print("File:", file.field_name, file.file_name, file.file_object.read())


parse_form(headers, BytesIO(body), on_field, on_file)

Output:

Field: b'username' = b'alice'
File: b'avatar' b'cat.txt' b'meow'

parse_form reads the body in chunks and calls your functions:

  • on_field runs for every text field.
  • on_file runs for every uploaded file.

Small files stay in memory. Once a file grows past 1 MiB, it is moved to a temporary file on disk, so a large upload does not fill up your memory.

Real servers do not use BytesIO. In a real application, the body comes from the network. Any object with a read() method that returns bytes works.

Handle each chunk yourself

parse_form still saves every file somewhere. When you want full control, for example to send an upload straight to cloud storage, use MultipartParser:

from python_multipart import MultipartParser

chunks = [
    b"--boundary\r\n",
    b'Content-Disposition: form-data; name="avatar"; filename="cat.txt"\r\n\r\n',
    b"me",
    b"ow\r\n--boundary--\r\n",
]


def on_part_data(data, start, end):
    print("Got a piece of the file:", data[start:end])


parser = MultipartParser("boundary", callbacks={"on_part_data": on_part_data})
for chunk in chunks:
    parser.write(chunk)
parser.finalize()

Output:

Got a piece of the file: b'me'
Got a piece of the file: b'ow'

The file arrived in two chunks, and you saw each one as it arrived. Nothing was stored.

Instead of copying data, the parser passes you a buffer plus start and end positions that mark the part you care about.

Learn more

License

Apache 2.0. See LICENSE.txt.

Metadata

Release files for python-multipart 0.0.34

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-multipart 0.0.34
File Size Uploaded Provenance Actions
python_multipart-0.0.34.tar.gz 52.5 kB With provenance Details for python_multipart-0.0.34.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for python-multipart 0.0.34
File Interpreter ABI Platform Actions
python_multipart-0.0.34-py3-none-any.whl Python 3 none any Details for python_multipart-0.0.34-py3-none-any.whl

Total release size: 85.0 kB

Release files / python_multipart-0.0.34.tar.gz

Download URL python_multipart-0.0.34.tar.gz
Size 52.5 kB
Tags Source
SHA-256 checksum
How to use checksums
b998ae90ca6e1e363261ce2e0e230281b8af53867b757970abd69ee9edcd843a
BLAKE2b-256 checksum
How to use checksums
7ec0c753d487a83d873f6946cee6cbc26cea3fe59a476ad0de99a14938a2fbd8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / python_multipart-0.0.34-py3-none-any.whl

Download URL python_multipart-0.0.34-py3-none-any.whl
Size 32.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ebacd224bd686eee2f9aa1066a657affe07435a185834e05e5235e2e59173e91
BLAKE2b-256 checksum
How to use checksums
f50e090c52b122d8ec5fa37942c1410fea9cf04ce98bca0c84dde7f0aa11594d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for python-multipart 0.0.34

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for python_multipart-0.0.34.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.34 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page