Skip to main content

content-types 🗃️🔎

PyPI version Python versions License: MIT Docs

A comprehensive Python library to map file extensions to MIME types with 360+ supported formats. It also provides a CLI for quick lookups right from your terminal. If no known mapping is found, the tool returns application/octet-stream.

Unlike other libraries, this one does not try to access the file or parse the bytes of the file or stream. It just looks at the extension which is valuable when you don't have access to the file directly. For example, you know the filename but it is stored in s3 and you don't want to download it just to fully inspect the file.

📚 Documentation

Full documentation is hosted at mkennedy.codes/docs/content-types. There you'll find a searchable API reference for get_content_type(), the complete extension-to-type mapping, and the shortcut constants. The quick examples below cover the essentials.

Extensive Format Support

With 360+ file extensions mapped, content-types covers:

  • 🎨 Images - Standard formats plus RAW camera files (Canon, Nikon, Sony, Adobe DNG, etc.)
  • 🎵 Audio - MP3, FLAC, AAC, MIDI, WMA, ALAC, DSD, and more
  • 🎬 Video - MP4, MKV, WebM, FLV, and modern codecs
  • 📦 Archives - ZIP, TAR, 7Z, RAR, plus modern formats (bz2, xz, zstd, brotli)
  • 📄 Documents - PDF, Office formats (DOCX, XLSX, PPTX), OpenDocument
  • 💻 Programming - Python, JavaScript, TypeScript, Rust, Go, Java, C++, Swift, Kotlin, and 25+ languages
  • 🔬 Data Science - Parquet, Jupyter notebooks, HDF5, Arrow, Pickle, NumPy, R, Stata, SAS, SPSS
  • ⚙️ Configuration - YAML, TOML, JSON, INI, ENV, dotfiles
  • 🐳 DevOps - Dockerfiles, Terraform, Kubernetes configs, Nomad
  • 🎨 Creative Suite - Adobe (PSD, InDesign, Premiere, After Effects), CAD files (AutoCAD, SketchUp, Blender)
  • 🎮 Game Development - Unity, Unreal Engine, PAK files
  • 🔬 Scientific - FITS, DICOM, NIfTI, PDB (protein data)
  • ⛓️ Blockchain - Solidity, Vyper smart contracts
  • 🗄️ Databases - SQLite, Access, MySQL files
  • 📝 Documentation - Markdown, AsciiDoc, Org-mode, BibTeX

...and much more!

Why not just use Python's built-in mimetypes? Or the excellent python-magic package? See below.

Installation

Requires Python 3.10 or later.

uv pip install content-types

Usage

import content_types

# Forward lookup: filename -> MIME type
the_type = content_types.get_content_type("example.jpg")
print(the_type)  # "image/jpeg"

# Works with any supported extension
print(content_types.get_content_type("data.parquet"))  # "application/vnd.apache.parquet"
print(content_types.get_content_type("notebook.ipynb"))  # "application/x-ipynb+json"
print(content_types.get_content_type("photo.cr2"))  # "image/x-canon-cr2"
print(content_types.get_content_type("model.blend"))  # "application/x-blender"
print(content_types.get_content_type("contract.sol"))  # "text/x-solidity"

# For very common files, you have shortcuts:
print(f'Content-Type for webp is {content_types.webp}.') 
# Content-Type for webp is image/webp.

# Data science shortcuts
print(content_types.parquet)  # "application/vnd.apache.parquet"
print(content_types.ipynb)    # "application/x-ipynb+json"
print(content_types.pkl)      # "application/octet-stream"
print(content_types.yaml)     # "application/yaml"
print(content_types.toml)     # "application/toml"
print(content_types.sqlite)   # "application/vnd.sqlite3"

# Works with Path objects too
from pathlib import Path
path = Path("document.pdf")
print(content_types.get_content_type(path))  # "application/pdf"

# URLs work too — query strings and fragments are stripped before lookup
url = "https://cdn.example.com/song.mp3?cache_id=678c2a"
print(content_types.get_content_type(url))  # "audio/mpeg"

# Unknown extensions fall back to 'application/octet-stream' by default;
# pass treat_as_binary=False to fall back to 'text/plain' instead.
print(content_types.get_content_type("notes.unknownext"))  # "application/octet-stream"
print(content_types.get_content_type("notes.unknownext", treat_as_binary=False))  # "text/plain"

# Or supply your own fallback for unknown extensions; it takes precedence
# over treat_as_binary. Known extensions still resolve normally.
print(content_types.get_content_type("notes.unknownext", fallback="application/x-custom"))  # "application/x-custom"

CLI

To use the library as a CLI tool, just install it with uv or pipx.

uv tool install content-types

Now it will be available machine-wide.

content-types example.jpg
# Outputs: image/jpeg

content-types data.parquet
# Outputs: application/vnd.apache.parquet

content-types notebook.ipynb
# Outputs: application/x-ipynb+json

content-types photo.cr2
# Outputs: image/x-canon-cr2

More correct than Python's mimetypes

When I first learned about Python's mimetypes module, I thought it was exactly what I need. However, it doesn't have all the MIME types. And, it recommends deprecated, out-of-date answers for very obvious types.

For example, mimetypes has .xml as text/xml where it should be application/xml (see MDN).

And mimetypes is missing important types such as:

  • .m4v -> video/mp4
  • .tgz -> application/gzip
  • .flac -> audio/flac
  • .epub -> application/epub+zip
  • .parquet -> application/vnd.apache.parquet
  • .ipynb -> application/x-ipynb+json
  • .mkv -> video/x-matroska
  • .toml -> application/toml
  • .yaml -> application/yaml
  • .rs -> text/x-rust
  • .go -> text/x-go
  • .tsx -> text/tsx
  • .psd -> image/vnd.adobe.photoshop
  • .dwg -> application/acad
  • ... and 300+ more

With this library, you get 360+ file extensions properly mapped, compared to Python's mimetypes which only has around 100 and includes outdated MIME types.

Here are some commonly used formats by category:

Data Science & Analytics:

  • .parquet - Apache Parquet columnar storage
  • .ipynb - Jupyter Notebooks
  • .pkl, .pickle - Python pickle files
  • .npy, .npz - NumPy arrays
  • .arrow, .feather - Apache Arrow
  • .hdf5, .h5 - HDF5 scientific data
  • .mat - MATLAB data files
  • .dta - Stata data files
  • .sav - SPSS data files

Modern Programming Languages:

  • .rs - Rust
  • .go - Go/Golang
  • .ts, .tsx - TypeScript/React
  • .jsx - React JavaScript
  • .vue - Vue.js components
  • .swift - Swift
  • .kt, .kts - Kotlin
  • .dart - Dart
  • .sol - Solidity (smart contracts)

Configuration & Infrastructure:

  • .yaml, .yml - YAML configs
  • .toml - TOML configs
  • .env - Environment variables
  • .dockerfile - Docker files
  • .tf, .tfvars - Terraform
  • .ini, .conf, .cfg - Configuration files

Creative & Design:

  • .psd, .psb - Adobe Photoshop
  • .indd - Adobe InDesign
  • .aep - Adobe After Effects
  • .dwg, .dxf - AutoCAD
  • .skp - SketchUp
  • .blend - Blender
  • .cr2, .cr3 - Canon RAW
  • .nef - Nikon RAW
  • .dng - Adobe DNG RAW

Modern Media:

  • .mkv - Matroska video
  • .webp - WebP images
  • .avif - AVIF images
  • .opus - Opus audio
  • .flac - FLAC audio
  • .midi, .mid - MIDI

Works when python-magic package doesn't

Why not the excellent python-magic package? That one works by reading the header bytes of binary files which requires access to the file data. The whole goal of this project is to avoid accessing or needing the file data. They are for different use-cases.

Contributing

Contributions are welcome! Check out the GitHub repo for more details on how to get involved.

Development

pytest and ruff aren't declared dependencies — uv provides them on the fly:

# Run the test suite (35 tests)
uv run --with pytest pytest

# Lint and format (config in ruff.toml)
uvx ruff check .
uvx ruff format .

Building the docs

The docs site is built with Great Docs and published at mkennedy.codes/docs/content-types. Great Docs imports the package for API introspection, so the toolchain lives in the dev extra and needs an editable install:

# Install the docs toolchain into your virtualenv
uv pip install -e ".[dev]"

# Build the site (mirrors great-docs/_site/ into the committed docs/ folder)
python scripts/build_docs.py

# Preview exactly as hosted, under the /docs/content-types subpath
python scripts/serve_docs.py   # -> http://127.0.0.1:8099/docs/content-types/

Metadata

Release files for content-types 0.4.1

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

Source distribution (sdist)

Source distribution for content-types 0.4.1
File Size Uploaded Provenance Actions
content_types-0.4.1.tar.gz 14.5 kB Without provenance Details for content_types-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for content-types 0.4.1
File Interpreter ABI Platform Actions
content_types-0.4.1-py3-none-any.whl Python 3 none any Details for content_types-0.4.1-py3-none-any.whl

Total release size: 26.3 kB

Release files / content_types-0.4.1.tar.gz

Download URL content_types-0.4.1.tar.gz
Size 14.5 kB
Tags Source
SHA-256 checksum
How to use checksums
56d0e19c3046dff76f0f005ee909e940fbae245cbaa0267b69a4bf39b04257a7
BLAKE2b-256 checksum
How to use checksums
46386d7eedfa552158badc1cc422568c9a9981f80c36cc113e08f898d331c002
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.20 {"installer":{"name":"uv","version":"0.11.20","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / content_types-0.4.1-py3-none-any.whl

Download URL content_types-0.4.1-py3-none-any.whl
Size 11.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1030c06d7384e365dcb16f052548c8ea0d11a390e8ae247272846c23d4ffedeb
BLAKE2b-256 checksum
How to use checksums
149b79f4839f7121cd9a1dd213ebb2d2f16e9affff24eaeb97aed9177ac17af8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.20 {"installer":{"name":"uv","version":"0.11.20","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for content-types 0.4.1

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

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