Python mimetypes: MIME Types

Applications that accept uploads, send attachments, serve downloads, or generate HTTP responses need to describe the format of their content. Python mimetypes provides a table-driven mapping between filename extensions and MIME media types, turning names such as report.pdf into application/pdf or listing possible extensions for a known type.

The module is useful in APIs, web servers, storage systems, email clients, and document pipelines. However, it mainly examines a filename, path, or URL. It does not open the file and does not prove that the bytes match the declared type. This guide explains the modern API, the distinction between media type and encoding, custom databases, portability concerns, and secure upload design.

It complements our guides to Python tempfile, fileinput, importlib.resources, shlex, and filecmp.

What a MIME type represents

A MIME type describes a general category and a specific format. It normally contains two parts separated by a slash, such as text/plain, image/png, application/json, or audio/mpeg. In HTTP, the value usually appears in the Content-Type header.

The type helps a consumer decide how to interpret bytes, but it is not a security guarantee. Browsers, libraries, operating systems, and antivirus tools may apply additional checks, and an attacker can give a malicious file an innocent extension.

Guessing the type of a file path

On modern Python versions, use guess_file_type() when the input is a filesystem path.

import mimetypes

media_type, encoding = mimetypes.guess_file_type("report.pdf")
print(media_type)  # application/pdf
print(encoding)    # None

The function returns a tuple. The first element is a MIME type or None when the suffix is missing or unknown. The second element identifies a filename encoding such as gzip.

Using guess_type for URLs

guess_type() remains the interface intended for URLs. Since Python 3.13, passing a local file path to it is softly deprecated; new path-oriented code should call guess_file_type().

media_type, encoding = mimetypes.guess_type(
    "https://example.com/download/data.json"
)
print(media_type)  # application/json

The separation matters on Windows and in tools that process both URLs and paths, because drive letters, backslashes, and URL schemes have different semantics.

Media type and encoding are different

A compound filename such as backup.tar.gz may return two pieces of information.

media_type, encoding = mimetypes.guess_file_type("backup.tar.gz")
print(media_type)  # application/x-tar
print(encoding)    # gzip

The encoding value is suitable for an HTTP Content-Encoding header. It is not a character set, and it is not the same as an email Content-Transfer-Encoding.

Strict and lenient lookup

Lookup functions default to strict=True, which prioritizes official registered media types. With strict=False, the module also considers common non-standard associations.

media_type, encoding = mimetypes.guess_file_type(
    "picture.pict",
    strict=False,
)

Strict mode is often preferable for public APIs and stable contracts. Lenient mode can help desktop applications, import tools, and compatibility layers that need to recognize older formats.

Guessing an extension

guess_extension() maps a MIME type to one possible extension.

extension = mimetypes.guess_extension("image/png")
print(extension)  # .png

The result is a convention, not proof that a byte stream used that extension. Some media types have multiple valid suffixes, and local operating-system databases can affect the result.

Listing all extensions

extensions = mimetypes.guess_all_extensions("image/jpeg")
print(extensions)

This is useful for file-picker filters, import rules, configuration validation, and conversion tools. Do not depend on a universal ordering of the returned list.

Registering a custom type

Applications can add private or vendor-specific formats with add_type().

mimetypes.add_type(
    "application/vnd.example.report+json",
    ".xreport",
)

media_type, _ = mimetypes.guess_file_type("monthly.xreport")

A valid extension starts with a dot. The Python 3.14 documentation warns that invalid undotted extensions will raise ValueError in Python 3.16, so existing registrations should be corrected now.

Global state and isolated databases

mimetypes.add_type() modifies process-wide tables. In applications with plugins, test suites, tenants, or separate client policies, that change may leak between components.

Create a MimeTypes instance when you need an isolated database.

database = mimetypes.MimeTypes()
database.add_type("application/x-project", ".proj")
print(database.guess_file_type("data.proj"))

Independent instances make behavior easier to test and prevent one integration from silently changing all later lookups.

Initialization and operating-system data

The module may combine its built-in mappings with installed mime.types files and, on Windows, registry data. The same suffix can therefore produce different answers on different machines.

mimetypes.init(files=[])

An empty list prevents system defaults from being loaded and keeps only the built-in well-known values. This can improve reproducibility in containers, tests, and controlled server deployments.

Loading a custom mime.types file

mimetypes.init(files=["config/mime.types"])

Later files take precedence over earlier ones. Treat the file as trusted configuration, keep it under version control, and review collisions before deployment.

Reading mappings without relying on success

read_mime_types() parses a mapping file and returns a dictionary.

mapping = mimetypes.read_mime_types("config/mime.types")
if mapping is None:
    raise RuntimeError("MIME mapping file is unavailable")

A None return means the file was missing or unreadable. It is different from an empty mapping.

Uploads: a suffix does not validate bytes

An attacker can rename payload.exe to photo.jpg. The module will answer from the name and can report image/jpeg. Secure upload processing therefore needs multiple controls:

• strict size limits;
• an allowlist of business-approved formats;
• content inspection with a format-aware library;
• server-generated storage names;
• storage outside the public web root;
• malware scanning or sandboxing when appropriate;
• safe response headers.

The browser-supplied content type is also untrusted client input.

Serving downloads safely

media_type, encoding = mimetypes.guess_file_type(path)
content_type = media_type or "application/octet-stream"

application/octet-stream is a sensible fallback for unknown bytes. When content must be downloaded rather than rendered, also use a safe Content-Disposition: attachment header and remove control characters from filenames.

Do not invent a charset

A result such as text/plain does not reveal whether the file uses UTF-8, Latin-1, UTF-16, or another character encoding. Add charset=utf-8 only when the application controls or has reliably detected the text encoding.

Compressed filenames

For names such as data.json.gz, the module can separate the underlying media type from compression. That is useful for HTTP metadata, but the application should still verify the format and limit decompression to prevent archive or compression bombs.

URLs with query parameters

Extract the URL path before guessing when query strings or fragments are present.

from urllib.parse import urlparse

url = "https://example.com/image.png?version=2"
path = urlparse(url).path
media_type, encoding = mimetypes.guess_type(path)

This avoids treating parameters as part of the suffix.

Email attachments

MIME lookup can help split a type into an email attachment’s main type and subtype.

media_type, _ = mimetypes.guess_file_type("contract.pdf")
main_type, sub_type = (media_type or "application/octet-stream").split("/", 1)

Read attachments in binary mode, reject arbitrary paths, and remember that the recipient still needs protection against malicious content.

Reproducible tests

Because operating-system mappings can extend the database, tests should control initialization or assert only guaranteed built-in types. Include files without suffixes, uppercase extensions, compound suffixes such as .tar.gz, custom types, unknown media types, and Unicode filenames.

Command-line interface

The module can also run as a command.

python -m mimetypes image.png
python -m mimetypes --extension application/json
python -m mimetypes --lenient picture.pict

This provides a convenient diagnostic tool in a container, server, CI job, or support session.

Common mistakes

• Treating the extension as content validation.
• Confusing Content-Encoding with a text charset.
• Using guess_type() for new local-path code.
• Ignoring None results.
• Mutating global tables during every request.
• Assuming identical mappings on every operating system.
• Registering extensions without a leading dot.
• Rendering unknown content inline in a browser.

Best practices

• Use guess_file_type() for paths.
• Fall back to application/octet-stream.
• Inspect content bytes independently for uploads.
• Use isolated MimeTypes databases for separate policies.
• Version custom mapping files.
• Test every supported platform.
• Do not infer a charset from the media type alone.
• Generate server-side filenames and enforce allowlists.

Conclusion

Python mimetypes is a focused utility for mapping filenames, paths, URLs, extensions, and MIME media types. It simplifies attachments, downloads, HTTP responses, and configuration interfaces when code handles media type and encoding as separate concepts.

Its limitation is intentional: answers come from tables and names, not from byte-level analysis. Use it for metadata and convenience, then combine it with real format validation, upload policies, and safe headers. Consult the official mimetypes documentation and the IANA media types registry when defining public or vendor-specific formats.