mimetype: Go MIME type detection from magic numbers without C bindings

mimetype detects MIME types from file content, not file names

Most file upload pipelines face a specific problem: a file arriving over HTTP may have any name the sender chose, and the Content-Type header can be wrong or absent. mimetype sidesteps both by reading the file header directly. It compares byte sequences against known magic numbers, which are fixed byte patterns at predictable offsets that identify file formats.

The project is written in Go and has no C bindings. libmagic, the standard Unix tool for the same job, is a C library that requires a shared object to be present on the system. mimetype is a pure-Go alternative that links statically into the binary at build time, avoiding the need to manage a system-level dependency or worry about C toolchain availability in a container.

The package is goroutine-safe by design. Multiple goroutines can call its detection functions concurrently without coordination. This matters in a service that processes uploads in parallel, because a detection library that requires external locking would add complexity at every call site.

The README's supported_mimes.md file lists the complete set of MIME types the library knows. The list includes formats from images and audio to documents, archives and code files. Common file formats are prioritized in the detection order, which means the most frequently encountered types are matched before less common ones.

A hierarchical detection tree rules out format families before checking subtypes

mimetype does not run every known format check against every file. Its detection logic is arranged as a hierarchy that rules out groups of formats before narrowing to a specific type.

The README gives the relationship between ZIP and Microsoft Office documents as the clearest example: Office files are ZIP archives containing specific metadata files. Once mimetype identifies a file as a ZIP, it proceeds to check whether that ZIP is an Office document. It skips the text file check entirely, because a ZIP cannot also be a text file. This ordering reduces the total number of checks needed to reach a specific MIME type.

The hierarchy also covers the binary versus text distinction. mimetype includes text versus binary file differentiation as a documented feature, and that classification sits high in the tree so it narrows the search space early.

The same principle applies to other container formats. A file that passes the initial checks for a common container format goes down that branch of the tree; formats that do not share that container are never evaluated. The tree.go file at the repository root implements this structure. The number of detection calls for any given file depends on where in the tree its format lives, not on the total count of supported types.

Install with go get and detect from bytes, a reader or a file path

Installation uses the standard Go toolchain:

go get github.com/gabriel-vasile/mimetype

The go.mod in the repository declares a minimum Go version of 1.24. Three detection functions cover the main use cases:

mtype := mimetype.Detect([]byte)
// OR
mtype, err := mimetype.DetectReader(io.Reader)
// OR
mtype, err := mimetype.DetectFile("/path/to/file")
fmt.Println(mtype.String(), mtype.Extension())

Detect takes a byte slice and returns synchronously. DetectReader and DetectFile can return errors, since they involve I/O. All three return a value whose String() method gives the MIME type string and whose Extension() method gives the associated file extension.

Detect is suited to cases where the file content is already in memory. DetectFile is the most convenient when working with a file path. DetectReader is for streaming contexts where the full file is not buffered, since mimetype reads only as many bytes as its current limit requires.

The package page on pkg.go.dev at https://pkg.go.dev/github.com/gabriel-vasile/mimetype#pkg-overview includes runnable Go Playground examples for each detection function and for the extension use case.

SetLimit controls how many header bytes are read; some formats need a full megabyte

By default, mimetype reads only the file header rather than the entire file. This limit exists to keep memory use low and detection fast. For most formats, a few hundred bytes at the start of the file contain all the magic bytes needed.

For some formats, that default limit is not enough. Certain file formats, including Microsoft Office documents, store their signatures towards the end of the file rather than at the start. When a format is in the supported list but mimetype does not identify it correctly, the fix is to increase the byte limit:

mimetype.SetLimit(1024*1024) // Set limit to 1MB.
// or
mimetype.SetLimit(0) // No limit, whole file content used.
mimetype.DetectFile("file.doc")

SetLimit(0) disables the limit entirely and causes mimetype to read the whole file before returning. For large files this changes the memory profile significantly. A 50 MB Office document would require 50 MB of memory to hold during detection, which may be acceptable for batch processing but is a problem for a high-concurrency upload endpoint.

The limit is a global setting. Changing it with SetLimit affects all subsequent calls in the process. For services that need different limits for different file types, the global state is a constraint to plan around; there is no per-call limit option in the current API.

go.mod retracts v1.4.14 the same day it was tagged; v1.4.15 fixed a 32-bit overflow

The go.mod file at the repository root contains two retract directives with inline comments that explain each one.

v1.4.14 is retracted with the comment "had an int overflow causing slice index panic on 32bit arch. #829". The version history shows v1.4.14 was tagged on 2026-07-22 and v1.4.15, which fixed the overflow, followed on 2026-07-23. When Go module tooling resolves a dependency and encounters a retracted version, it emits a warning and declines to use that version automatically. Any go.sum file that pinned v1.4.14 before the retraction should be updated to v1.4.15.

The second retraction covers v1.4.4, with the comment "had a test file detected as malicious by antivirus software. #575". That is a different kind of issue from a code bug: a file included in the testdata directory was flagging antivirus scanners. Developers who audit their Go module cache may encounter this warning when scanning older module caches that still hold v1.4.4.

The retract directive in go.mod is the correct mechanism for communicating both of these situations to the Go module system. It does not remove the tag from the repository, but it signals to anyone using go get or go mod tidy that these versions should not be selected.

The README's own caution: magic-number detection is inaccurate and a last resort

The project's own README includes a caution that is worth quoting directly: "only use libraries like mimetype as a last resort. Content type detection using magic numbers is slow, inaccurate, and non-standard. Most of the times protocols have methods for specifying such metadata; e.g., Content-Type header in HTTP and SMTP."

This is an honest description of the tradeoff. Magic numbers work because format designers place identifying bytes at a fixed position in the file, but there are formats whose signatures are ambiguous or absent. The README acknowledges inaccuracy explicitly rather than claiming universal correctness.

For a production service, this means the library is appropriate when there is genuinely no better source for content type. A file upload endpoint that strips or ignores the Content-Type header from the client and detects from the raw bytes has a stronger security argument than one that trusts the client's header, but it still carries the risk that mimetype returns a wrong answer for edge cases.

Benchmarks are run when a pull request is opened, and the results are visible on the workflows page. Performance improvements are welcome, but correctness comes first; that ordering is the right one for a detection library.

Testing against 50,000 files with libmagic, and how to extend the format list

mimetype's test infrastructure includes a separate repository, mimetype_tests, that compares the library against libmagic across around 50 000 sample files. The results of the latest comparison are visible on its GitHub Actions page. This comparison is the closest thing the project has to an independent accuracy benchmark.

libmagic is the C library behind the Unix file command, and it is the reference implementation for magic number detection. Comparing against it tells you where mimetype agrees with the established standard and where it diverges. Divergences are not automatically mimetype bugs; libmagic can also be wrong, and mimetype may prioritize a different MIME type string for the same format.

The package is extensible. The README links to a package-level example at pkg.go.dev that shows how to add detection for a file format not in the built-in list. A PR for a new format must include a test record in mimetype_test.go, and for complex files a sample can be added to the testdata/ directory. Code contributions must pass gofmt and have test coverage.

mimetype is distributed under MIT, and the last push was on 2026-09-28. For a Go service that needs pure-Go detection without a C library, and cannot rely on file name or protocol-level type metadata, this is the library the Go ecosystem has converged on for this use case.

Editorial conclusion

mimetype suits a Go service that cannot rely on file extensions or Content-Type headers and needs pure-Go detection that is safe for concurrent use. Skip it when the protocol already provides content type metadata, which the README names as the preferred path. Before relying on it for document processing, test it against your actual files with the SetLimit function, because formats like Microsoft Office documents store their signatures near the end of the file and may require SetLimit(0) to detect correctly.

Frequently asked questions

Official sources

1. gabriel-vasile/mimetype on GitHub
2. License: MIT
3. Project website
4. README
5. Releases