mktemp on macOS: It Ignores $TMPDIR, and 4 More Traps

On macOS 26.4.1 I set TMPDIR=/tmp/mkt/final/custom/, exported it, and ran mktemp -t build. The file came back as /var/folders/nw/1f_hl8c90g54vr86ph4dzjth0000gn/T/build.gn2ETvQl9c, exit code 0. The same line with GNU gmktemp wrote into /tmp/mkt/final/custom/, and so did Python's tempfile. Apple's mktemp was the only one of the three that ignored the variable.

That's the trap most likely to bite scripts written on Linux, and there are four more. I ran each one on the Mac mini that runs this business, then read Apple's published mktemp.c for 26 source versions to find out when each behavior started. Two of the five depend on which macOS you're on, and so does the fix.

Trap 1: $TMPDIR is ignored, on purpose

The source for the mktemp in macOS 26.4 (shell_cmds-329) has an #ifdef __APPLE__ block. When mktemp builds a name itself, from -t or with no arguments at all, it first asks confstr(_CS_DARWIN_USER_TEMP_DIR) for your per-user temp folder. It reads $TMPDIR only if that call fails, and on a normal login it doesn't fail:

$ export TMPDIR=/tmp/mkt/final/custom/
$ getconf DARWIN_USER_TEMP_DIR
/var/folders/nw/1f_hl8c90g54vr86ph4dzjth0000gn/T/
$ mktemp
/var/folders/nw/1f_hl8c90g54vr86ph4dzjth0000gn/T/tmp.twN8GUSxSw
$ mktemp -t build
/var/folders/nw/1f_hl8c90g54vr86ph4dzjth0000gn/T/build.gn2ETvQl9c
$ TMPDIR=. mktemp -d
/var/folders/nw/1f_hl8c90g54vr86ph4dzjth0000gn/T/tmp.ifiE8DJVBT

Most of the time you won't notice, because Terminal sets $TMPDIR to that same /var/folders/.../T/ path. It matters when you point $TMPDIR somewhere else on purpose: a bigger disk, a RAM disk, a build sandbox, or the current folder. The man page doesn't help much. One paragraph says _CS_DARWIN_USER_TEMP_DIR comes first. The -t entry says it uses "TMPDIR if set." The EXAMPLES section introduces mktemp -t with "To allow the use of $TMPDIR." On a normal login, that example ignores $TMPDIR.

Someone asked about exactly this in 2019 on Unix & Linux: mktemp on macOS not honouring $TMPDIR. TMPDIR=. mktemp works on Linux and OpenBSD for a temp file in the current folder, but on a Mac it went to /var/folders.

Since macOS 14 there are two ways to make mktemp use $TMPDIR. Both use the -p option, and both worked on 26.4.1:

$ mktemp -p "$TMPDIR" -t build
/tmp/mkt/final/custom/build.4nGQdNBi8G
$ mktemp --tmpdir -t build          # no value: falls back to $TMPDIR
/tmp/mkt/final/custom/build.aGJde5TI3k

On macOS 13 and older, -p is a usage error. The form that works on every version, and on GNU, is a full template path:

d=${TMPDIR:-/tmp}
f=$(mktemp "${d%/}/build.XXXXXX") || exit 1

The ${d%/} trims the trailing slash that macOS puts on $TMPDIR. Without it you get custom//build.Xf5MEb, which still works but looks broken in logs.

When each behavior arrived

Apple publishes the source for each macOS release in its distribution-macOS repository. I mapped all 166 release tags to the shell_cmds version they include, then fetched mktemp/mktemp.c from 26 of those versions. They cover 113 releases, from Mac OS X 10.5.2 to macOS 26.5. The code changes twice, and it splits those releases into three groups:

The switch to the per-user temp folder and the no-argument form arrived together in shell_cmds-187, which first shipped in OS X 10.11 El Capitan. That's why older answers disagree with each other. The top answer on "Fix or alternative for mktemp in OS X" (149 votes) says plain mktemp -d fails on "all versions before Mac OS X 10.11" and adds a fallback for them. In 2019, the notmuch project hit the same usage error on older OS X machines in the MacPorts build farm. Their message also explains why there was no easy fix then: -t /tmp breaks GNU, and the old Apple version had no -p.

Trap 2: -t takes a prefix, not a template

On GNU, -t is a flag and the template follows it. On macOS, -t takes the next word as its argument. That word becomes a prefix, and mktemp adds its own .XXXXXXXXXX after it. So the Linux habit of putting X's after -t keeps them as literal characters:

$ mktemp -t build.XXXXXX
/var/folders/nw/1f_hl8c90g54vr86ph4dzjth0000gn/T/build.XXXXXX.gyCB07fzb3

That one is harmless. Flag order is not. A 2015 Stack Overflow question used mktemp -t -d zombie.XXXXXXXXX. I ran the same line on 26.4.1, and it still does what it did then:

$ cd /tmp/mkt/z
$ mktemp -t -d zombie.XXXXXXXXX
/var/folders/nw/1f_hl8c90g54vr86ph4dzjth0000gn/T/-d.9NCjjERU1N
zombie.P5VFCwubH
$ echo $?
0

-t took -d as its prefix, so no directory was made. It created two files: one named -d.9NCjjERU1N in the temp folder, and one named zombie.P5VFCwubH in the current folder, because the template had no path. It printed two lines and exited 0. A script that does cd "$(mktemp ...)" then fails on a path containing a newline. Put -d first: mktemp -d -t zombie.

Trap 3: X's in the middle, or no X's, still succeed

GNU mktemp rejects a template with fewer than three X's at the end. Apple's version replaces only the X's at the very end of the template, and it accepts zero:

$ mktemp /tmp/mkt/final/report.XXXXXX.json
/tmp/mkt/final/report.XXXXXX.json            # rc=0, literal name
$ mktemp /tmp/mkt/final/report.XXXXXX.json
mktemp: mkstemp failed on /tmp/mkt/final/report.XXXXXX.json: File exists
$ mktemp /tmp/mkt/final/plain.txt
/tmp/mkt/final/plain.txt                     # rc=0
$ gmktemp /tmp/mkt/final/plain2.txt
gmktemp: too few X's in template '/tmp/mkt/final/plain2.txt'

So the first run works and the second run fails, which matches "mktemp on macOS random file generation fails: file exists". A typo like .XXXXX.log gives you a fixed, guessable file name and exit code 0, which defeats the point of mktemp.

Trap 4: there is no --suffix

The option people look for is GNU's --suffix=.json. Apple's version doesn't have it, and fails with mktemp: unrecognized option `--suffix=.json', exit 1. Two workarounds that don't race:

# 1) make a private directory, name the file yourself
d=$(mktemp -d) || exit 1
trap 'rm -rf "$d"' EXIT
f="$d/report.json"

# 2) install GNU coreutils and call gmktemp
gmktemp --suffix=.json "${TMPDIR:-/tmp}/report.XXXXXX"

The first one is what I'd use. The directory is mode drwx------, so the file name inside it doesn't need to be random. Appending .json to $(mktemp)'s output doesn't work: you get a name for a file that was never created, and the empty file mktemp did create is left behind.

Trap 5: the GNU long options depend on your macOS

On 26.4.1, mktemp --directory, --quiet, --dry-run and --tmpdir all work. They came with the getopt_long rewrite in shell_cmds-302.0.1, which first shipped in macOS 14.0. On macOS 13 and older, every one of them is a usage error. That's the error in the 2012 question, filed from OS X 10.6. --version and --suffix don't exist on any version, so you can't use mktemp --version to tell which mktemp you have. what /usr/bin/mktemp prints the build: PROJECT:shell_cmds-329 on this machine.

How often this comes up

I pulled every question with "mktemp" in the title from Stack Overflow, Super User, Unix & Linux and Ask Different through the Stack Exchange API. That's 61 questions with 454,489 views between them. Six are about macOS, with 69,424 views: the --directory question from 10.6 (50,189 views), the -t -d order (11,131), $TMPDIR (4,641), X's before an extension (1,654), Apple's own locate.updatedb failing with "too few Xs in template 'updatedb'" (1,140), and one about heredocs that isn't really about mktemp (669). Five of the six match the traps above. The sample is small, but the question with the most views is about the long-option gap, which macOS 14 closed.

The updatedb question shows the same traps work in reverse. Line 36 of /usr/libexec/locate.updatedb on 26.4.1 is FCODES=$(sudo -u nobody mktemp -t updatedb), Apple's prefix syntax. If you put Homebrew's GNU mktemp ahead of /usr/bin in your PATH to make Linux scripts work, Apple's own scripts that use -t fail instead. Calling gmktemp by name when you need GNU behavior avoids that.

If you use the /tmp fallback in the portable template, know that macOS 26 deletes old files there on its own schedule. I traced that in macOS /tmp cleanup. mktemp isn't the only BSD tool here that differs from GNU. The same kind of script also breaks on sed's "invalid command code" on Mac and on timeout and other GNU tools that macOS doesn't ship. My envsubst on Mac post uses bare tmp=$(mktemp) for an in-place rewrite. That's safe, because it doesn't care which folder the file lands in.

FAQ

Why does mktemp on macOS ignore TMPDIR?

Since OS X 10.11, Apple's mktemp asks the system for the per-user temp folder (confstr _CS_DARWIN_USER_TEMP_DIR, a path under /var/folders) whenever it builds the file name itself, with -t or with no arguments, and only reads TMPDIR if that lookup fails. On macOS 14 and later, mktemp -p "$TMPDIR" -t name or mktemp --tmpdir -t name uses TMPDIR. On any version, a full template such as mktemp "${TMPDIR:-/tmp}/name.XXXXXX" does.

Does mktemp on macOS support --suffix?

No. Apple's mktemp rejects --suffix with "unrecognized option" and exit code 1, and it only replaces X's at the very end of a template, so name.XXXXXX.json creates a file literally called name.XXXXXX.json. Make a private directory with d=$(mktemp -d) and create name.json inside it, or install GNU coreutils with Homebrew and use gmktemp --suffix=.json.

What is the portable mktemp command for macOS and Linux?

Give mktemp a full template with at least six trailing X's and no other options: mktemp "${TMPDIR:-/tmp}/name.XXXXXX" for a file, or mktemp -d "${TMPDIR:-/tmp}/name.XXXXXX" for a directory. That works on GNU coreutils and on every macOS version checked, from 10.5.2 to 26.5. Avoid -t (it means different things), long options (macOS 14 and later only) and --suffix (GNU only).

How this was checked: I ran every command above on 2026-10-15 on a Mac mini M4 with macOS 26.4.1 (build 25E253) and zsh 5.9, with Apple's /usr/bin/mktemp (shell_cmds-329) and Homebrew's GNU coreutils 9.12 gmktemp. The release groups come from Apple's published mktemp.c in 26 shell_cmds versions, matched to macOS releases through the submodule references in the distribution-macOS repository, so they show what Apple's source says, not tests on old Macs. I didn't check releases before 10.5.2. The Stack Exchange counts are a title search for "mktemp" on four sites on the same day; questions that use mktemp without naming it in the title aren't included. The temp files the tests created were deleted afterward.