Skip to main content

Getting started

Imagine someone hands you a sealed envelope and asks what is inside. You are not allowed to open it. All you get is the label on the front. That is the job content-types does, and it turns out the label is usually enough.

The envelope problem

Here is how the problem shows up in real code. You have a bucket in S3 with a few hundred thousand objects. A customer’s browser asks for one of them, and your job is to send back a Content-Type header so the browser knows whether to render an image, play audio, or offer a download. The honest way to find out is to fetch the object and look at its first few bytes. The honest way is also slow, costs money, and is silly when the key already says invoice-2026-03.pdf.

The same situation shows up when you are uploading. S3 will happily store report.pdf as binary/octet-stream if you let it, and then every link to that file becomes a download instead of a tab. You want to set the type correctly at upload time, and again, you already know the filename.

content-types answers the question from the label. It takes the extension, looks it up in a table of 364 entries, and returns the type. It never opens, reads, or sniffs anything, so it is safe to call on names of files that live on another machine, on URLs you have not fetched, and on files that do not exist yet.

Install

Requires Python 3.10 or later. There are no runtime dependencies, so it adds nothing to your lock file but itself.

uv add content-types
# or
pip install content-types

The first lookup

import content_types

content_types.get_content_type('report.pdf')
# 'application/pdf'

That is the whole core API. One function, one string in, one string out. The import name is content_types with an underscore; the distribution and the command line tool are content-types with a hyphen. Python cannot import a hyphen, so the two spellings are a fact of life.

It is not fussy about what you hand it

The function was written by someone who got tired of normalising filenames before every call, so it does the normalising for you. A full path, a bare extension with or without the dot, a pathlib.Path, or a URL all work, and case does not matter.

from pathlib import Path

content_types.get_content_type('photo.JPG')  # 'image/jpeg'
content_types.get_content_type('images/photo.jpg')  # 'image/jpeg'
content_types.get_content_type('jpg')  # 'image/jpeg'
content_types.get_content_type('.jpg')  # 'image/jpeg'
content_types.get_content_type(Path('/data/photo.jpg'))  # 'image/jpeg'
content_types.get_content_type('https://cdn.example.com/a.mp3?v=3#t=10')  # 'audio/mpeg'

Three details are worth knowing up front, because each one has surprised someone.

  • For URLs, the query string and the fragment are thrown away before the lookup. A cache-busting ?v=3 does not turn your MP3 into a mystery.
  • For compound extensions the last segment wins. archive.tar.gz resolves as gz and returns application/gzip, which is the right answer for the outer container. There is no special knowledge of .tar.gz as a unit.
  • Dotfiles such as .env and .gitignore are in the table and resolve to text/plain. They are extensions with no name in front, and the lookup treats them that way.

When the label is blank

Sometimes the envelope says Makefile, or notes.xyz, or nothing at all. For those the function returns application/octet-stream, the universal “it is bytes, I cannot tell you more” type. That is the correct thing to put in a header, but it is not always what you want in your own logic, and it hides the fact that a lookup missed. The next page, Unknown extensions, is about telling a miss from a hit and deciding what to do about it.

Shortcut constants

For a handful of formats you reach for daily, the module hands you the answer as a plain string so you do not even write the call.

content_types.json  # 'application/json'
content_types.pdf  # 'application/pdf'
content_types.parquet  # 'application/vnd.apache.parquet'

The full set is webp, png, jpg, mp3, json, pdf, zip, xml, csv, md, parquet, ipynb, pkl, yaml, toml, and sqlite. One caution: write import content_types and use attribute access. from content_types import json quietly shadows the standard library json module, and you will spend an unhappy afternoon wondering why json.loads is a string.

Where to go next

  • Unknown extensions is the detective work: telling a miss from a hit and the three ways to handle one.
  • Reverse lookup runs the envelope backwards, from a content type or a Content-Type header to an extension.
  • Command line covers the content-types tool for quick answers in a shell.
  • Compared to mimetypes explains why the standard library was not enough and how the table differs.
  • FAQ collects the questions people actually ask.
  • The API reference lists every public name with its signature.