mdls Command on Mac: Why It Prints (null) for Real Files

I wrote a 12-byte text file into a folder Spotlight indexes and ran mdls on it straight away. Every attribute came back (null), including kMDItemFSName, the file's own name, and the exit code was 0. About 1.3 seconds later the same command printed 30 attributes. Nothing about the file changed in between; the Spotlight index caught up.

That is the thing to understand about the mdls command on Mac: it mostly reads the Spotlight index, not the file. When the index has a record, you get the full set. When it does not, you get a short fallback list, a row of (null), or an error that says the file does not exist when it plainly does. Below are the four states I could produce on a Mac mini M4 running macOS 26.4.1, plus the output quirks that break scripts.

The four answers mdls gives

1. The file is indexed: the full list

For a settled text file in my home folder, mdls printed 30 attributes, among them kMDItemContentType = "public.plain-text", kMDItemDateAdded, kMDItemLogicalSize = 12 and kMDItemPhysicalSize = 4096. This is what every tutorial shows. On Tahoe there is also a new-looking kMDItemEmbeddingVersion = 3 row; mdimport -A lists it with no description, so I am not going to guess what it means.

2. The file was just written: a row of (null)

I created 12 fresh files in an indexed folder and polled mdls -raw -name kMDItemFSName about every 0.2 seconds until it returned something other than (null). It took between 1,253 and 2,324 ms, with a median of about 1,330 ms, and kMDItemContentType appeared in the same poll every time. During that window the default listing is 15 kMDItemFS* rows, all (null) except kMDItemFSInvisible = 0 and two empty type codes.

Overwriting a file has a smaller version of the same gap. I rewrote a 12-byte file with 20 bytes; mdls -raw -name kMDItemFSSize said 12 immediately and 20 four seconds later. A script that writes a file and reads its metadata on the next line can read the old record or no record at all, and the exit code will not tell it.

3. The file is not indexed: 15 file system rows

A file in /tmp, a file inside a folder named something.noindex, a dotfile in an indexed folder, and a file on a mounted disk image with indexing disabled all gave the same shape: exactly 15 kMDItemFS* rows, filled in from the file system, and nothing else. This is the case behind the Ask Different question 'mdls' does not display all metadata for hidden files, and behind a related one where a sort-by-date-added function gets (null) for dotfiles. In my test the dotfile's kMDItemDateAdded was (null).

Two details in this fallback are worth knowing:

• Asking by name gets more than the listing shows. The /tmp file's full listing had no kMDItemContentType, but mdls -name kMDItemContentType returned "public.plain-text", and -name kMDItemKind returned a value too. kMDItemPhysicalSize stayed (null).
• kMDItemFSNodeCount repeats the file size. A 1,000-byte file in /tmp reported kMDItemFSNodeCount = 1000 next to kMDItemFSSize = 1000, and a /tmp folder with 3 entries reported 3 for both. The 2018 hidden-file question above shows the same pair, 7376 and 7376, so this is not new. Node count is meant for folders, and in this fallback it should not be trusted for anything.

4. The volume is mounted -nobrowse: "could not find"

I made a 20 MB APFS image with hdiutil and attached it with -nobrowse. A file I had just written there, and could cat, gave:

$ mdls /tmp/mdlsprobe-mnt/f.txt
/tmp/mdlsprobe-mnt/f.txt: could not find /tmp/mdlsprobe-mnt/f.txt.
$ echo $?
1
$ mdutil -s /tmp/mdlsprobe-mnt
/System/Volumes/Data/private/tmp/mdlsprobe-mnt:
	Error: unknown indexing state.

That is word for word the situation in mdls does not work on mounted sparse bundles from 2020, which has no accepted answer. Attaching the same image normally under /Volumes gave Indexing disabled and the 15-row fallback from state 3 instead. If you need mdls on an image, attach it without -nobrowse. The image formats themselves are in my hdiutil notes.

Output quirks that break scripts

Even with a good index record, the output format has edges:

What I ran	What happened
mdls -raw -name kMDItemFSName a.txt	Prints a.txt with no trailing newline; your prompt lands on the same line
-raw with two -name flags, or two files	Values separated by NUL bytes (a.txt, NUL, 12), as the man page says, but with no NUL after the last one
find ... -print0 | xargs -0 mdls -raw -name ...	Because the last value has no separator, each xargs batch runs into the next: 17 files gave 12 lines, 5 of them two dates glued together (forced with -n 3)
-raw -name kMDItemContentTypeTree	An array comes out as one multi-line ( "...", "..." ) block, not NUL-separated items
mdls -name kMDItemFSName a.txt b.txt	Two lines, no file names; you have to track order yourself
-name FSName, -name kmditemfsname	(null), rc 0. Names are case-sensitive and need the kMDItem prefix
mdls -attr Keyword file (the example in mdls's own usage text)	Keyword = (null); the real attribute is kMDItemKeywords, as in Apple's common metadata attribute keys
Any date attribute	Printed in UTC with +0000: a file changed at 19:32:41 KST showed 10:32:41 +0000
kMDItemKind	Localized by the system language: "일반 텍스트 문서" on this Mac, unchanged by LANG=en_US.UTF-8
mdls link.txt on a symlink	Reports the target: kMDItemFSName = "a.txt"
-plist - with -raw	Refused: "-p and -plist may not be combined with -r", rc 1

The UTC dates are the subject of a 2014 Stack Overflow question; nothing is wrong with the file, the format just always uses +0000. For scripts, match on kMDItemContentType rather than kMDItemKind, because Kind changes with the language of the Mac. And -plist - gives dates in ISO 8601 with a Z, which is easier to parse than the default text; plutil can convert it to JSON.

The man page on this machine is dated June 3, 2004 and documents three options. Running mdls with no arguments prints a usage block with five, including -plist and -sdb, and short forms -n, -r, -m and -p. Both are shipped in the same macOS 26.4.1 install.

What people ask about mdls

To see whether these states match what trips people up, I pulled every question with "mdls" in the title from Stack Overflow, Ask Different, Super User and Unix & Linux through the Stack Exchange API: 23 questions in total.

Theme	Questions	Example
Scripting the output (parse, loop, recurse)	7	Does "mdls -recursive" exist? (no)
Values missing or (null)	6	dotfiles, network shares, sparse bundles, video files
Where the data comes from	4	tied for most votes: how mdls derives metadata
What a value means	3	UTC dates, bit rate, mediainfo differences
Other (editing, mdfind, alternatives)	3	reading Date Added without mdls

Six of 23 are about missing or (null) values, and the four states above cover the dotfile, disk image and "sometimes null for every file" reports. The most-viewed, using mdls to generate a metadata report, is a shell loop of exactly the kind that the 1.3-second gap and the no-newline -raw output break.

Using mdls safely in a script

# one value, newline added, null made explicit
mdls -raw -nullMarker NONE -name kMDItemContentType "$f"; echo

# many files: one mdls per file, so batches cannot glue together
find . -type f -print0 | while IFS= read -r -d '' f; do
  printf '%s\t' "$f"; mdls -raw -nullMarker NONE -name kMDItemDateAdded "$f"; echo
done

# just wrote the file? check that the index has it first
mdls -raw -name kMDItemFSName "$f" | grep -qv '^(null)$' || sleep 2

There is no recursive flag; pair it with find on Mac as above. A loop is slower than handing everything to xargs, but with -raw it is the version that keeps one value per line. For searching rather than reading one file, mdfind queries the same index and has its own blind spots. Where a value is stored as an extended attribute, as kMDItemWhereFroms is, mdls reads it from the file: I wrote a binary plist to com.apple.metadata:kMDItemWhereFroms on a curl download, which had none, and mdls showed both URLs five seconds later. The quarantine xattr works the same way.

FAQ

Why does mdls show (null) for a file that exists?

Either Spotlight has not indexed it yet, or it will never index it. A file written seconds ago returns (null) for every attribute for about 1.3 to 2.3 seconds. Files in /tmp, in .noindex folders, dotfiles and files on volumes with indexing off return only 15 kMDItemFS attributes, so anything else, such as kMDItemDateAdded, is (null).

How do I get only the value from mdls without the attribute name?

Use mdls -raw -name kMDItemContentType file. The value is printed without a trailing newline, so add echo after it, and multiple values are separated by NUL bytes rather than newlines. Add -nullMarker with a string of your choice to replace (null).

Why does mdls say "could not find" for a file I can open?

The file is on a volume Spotlight does not track at all, typically a disk image or sparse bundle attached with -nobrowse. mdutil -s on that mount reports "unknown indexing state". Attaching the image without -nobrowse makes mdls return the basic file system attributes again.

How this was checked: every command ran on 2026-10-16 on a Mac mini M4 with macOS 26.4.1 (25E253) against /usr/bin/mdls, in a working folder under my home directory that Spotlight indexes, plus /tmp, a .noindex folder and a 20 MB APFS disk image attached with and without -nobrowse. The timing figures come from 12 new files polled about every 0.2 seconds, so they are accurate to roughly that interval. The attribute count of 288 (216 kMDItem, 52 _kMDItem, 20 others) is from mdimport -A on the same Mac. The 23 questions are every Stack Exchange API result for "mdls" in the title on the four sites named, grouped by me; the scripts and raw output are in my research folder.