textutil on Mac: .docx Drops Tables, Failed Reads Exit 0

I asked textutil to convert a file that doesn't exist. It printed Error reading missing.docx. The file doesn’t exist. to stderr, wrote nothing, and exited 0. The man page on this Mac, dated September 9, 2004, says "The textutil command exits 0 on success, and 1 on failure." In my tests, a failed read was exit 0 every time I tried it: a missing file, a real PDF, a Windows-1252 text file, an HTML page whose image never loaded.

The second surprise came from the output side. I wrote an HTML file with a table, two lists, a link and an image, and converted it to all nine formats textutil can write. The .docx it produced has no table, no hyperlink, no Word list and no picture. The text is all there, so the file opens fine and looks plausible until you scroll to where the table was. Below is what I measured on a Mac mini running macOS 26.4.1, with /usr/bin/textutil at 173,088 bytes: the writer matrix, the read side using Word-made test files, the exit codes, text encodings, HTML timeouts and batch speed.

What textutil does

textutil is the command-line front end to the same document readers and writers TextEdit uses. It has three verbs: -info prints a file's type and length, -convert fmt writes one output file per input, and -cat fmt joins all inputs into one. The formats are txt, rtf, rtfd, html, doc, docx, odt, wordml and webarchive. Everything else is an option on top of those: -output, -stdout, -encoding and -inputencoding, -noload and -timeout for HTML, and a set of metadata flags like -title and -author. The full list is in the textutil(1) man page.

textutil -convert txt report.docx                 # writes report.txt next to it
textutil -convert html notes.rtf -output out.html
textutil -convert txt report.docx -stdout | wc -w
textutil -cat txt part1.docx part2.rtf -output all.txt

It cannot write PDF or Markdown. -convert pdf, -convert md and -convert markdown all stop with Invalid output format. and exit 1, which is the one error that does get a non-zero status. Format names are case-insensitive: -convert TXT works.

What each output format keeps

The source was one HTML file with a heading, bold, italic, underline and strikethrough text, a link, a nested bullet list, a numbered list, a 3-row table, an inline PNG, and text in Korean, Japanese and emoji. I converted it to each format and checked the result two ways: by reading the file's own XML where I could (docx, wordml, odt), and by converting it back to HTML with textutil and looking for each element.

Inside the .docx, word/document.xml has zero <w:tbl>, zero <w:hyperlink>, zero <w:numPr> and zero <w:drawing> elements, and the zip has no word/media folder. Bold and strikethrough are there as run properties. The table became six separate paragraphs, one per cell. The lists became paragraphs that start with a tab, a literal "•" or "1", and another tab, so Word shows something that looks like a list but won't renumber or indent as one. The link text is plain text with the URL gone. The .wordml output (Word 2003 XML) has exactly the same counts. I also started from the .rtfd version, which carries the PNG as an attachment, and converted that to docx, odt, doc and wordml: none of the four contained the image.

If you need a Word file with tables from the command line, write .odt instead. It kept the table, both lists and the link, and Word opens .odt files. Or write .rtf, which kept everything except the image.

The HTML writer has two quirks of its own. The image came out as <img src="file:///Attachment.png">, while the PNG itself was saved next to the output file, so a browser looks for it at the root of the disk and shows a broken image. And the nested bullet list was written as a <ul> placed directly inside the parent <ul>, not inside an <li>, which isn't valid HTML. That's the complaint in textutil producing invalid list html output, asked in February 2014 and still unanswered; it's still true on 26.4.1.

Reading Word files made by Word

My own docx only tells you what textutil writes. To test reading, I used four .docx files from the python-docx test suite whose docProps/app.xml says they were saved by Microsoft Word, and converted each to HTML.

Word file	In the .docx	In textutil's HTML
tbl-having-tables.docx	3 tables	3 tables
par-hyperlinks.docx	4 hyperlinks	0 links; the link text stays as plain text
shp-inline-shape-access.docx	5 inline drawings, 2 image files	0 images, and no placeholder character either
A docx I built by hand with a decimal list	numbered list, 2 items	bullet list ("•"), numbers gone

So reading is better than writing for tables, and worse for everything else. If you're using textutil -convert txt *.docx to pull text for search or word counts, that's fine: the words come through. If you're converting Word files to HTML for a website, the links and images will be missing and nothing will tell you.

Exit codes: what returns 0 and what returns 1

Case	Exit	What happens
Input file doesn't exist	0	"The file doesn’t exist." on stderr, no output
Real PDF as input	0	"Text encoding Unicode (UTF-8) isn’t applicable."
PNG as input	0	Same encoding message
One good file and one missing file with -convert	0	Good file converted, error for the other
One missing file among four with -cat	1	No output at all, the other three are lost too
Output file already exists	0	Overwritten without asking
-output into a folder that doesn't exist	1	"The folder doesn’t exist."
-output pointing at a directory	1	"couldn’t be saved in the folder"
-convert pdf or md	1	"Invalid output format."
-encoding windows-1252 with Korean text	1	Write error, no file
-inputencoding bogus-enc	0	The option is ignored, auto-detection runs

The pattern is: errors while writing return 1, errors while reading return 0. A script can't rely on $? after a conversion. Check that the output file exists and isn't empty, or check stderr. I covered the same habit for pipes in the bash pipe exit code post; textutil hides failures without a pipe.

Two more behaviors worth knowing. A file named fake.docx that is really plain text converts without complaint, because textutil sniffs the content rather than trusting the extension. And with several input files, -output only renames the first one; the rest get their default names next to their sources. The same goes for -stdout, which printed only the first of two files.

Text encodings and the PDF that turns to gibberish

For plain-text input, textutil detects UTF-8, and UTF-16 if there's a byte order mark. For anything else it falls back to the account's legacy encoding, which comes from ~/.CFUserTextEncoding or the __CF_USER_TEXT_ENCODING environment variable. On this Mac that file says 0x3:0x33; the 3 is Korean. So an EUC-KR file converted correctly with no flags, and a Windows-1252 file with "Café" in it failed with the UTF-8 message and exit 0. A UTF-16 file without a BOM, a Shift JIS file and a MacRoman file failed the same way.

Then I set __CF_USER_TEXT_ENCODING=0x1F5:0x0:0x0, where encoding 0 is MacRoman, the Roman-script default. The same Windows-1252 file now converted, with exit 0, as CafÈ naÔve rÈsumÈ. No error at all, just wrong letters. The fix in both cases is to say what the file is:

textutil -inputencoding windows-1252 -convert txt old.txt -output new.txt
textutil -inputencoding euc-kr -convert txt korean.txt -output out.txt
textutil -inputencoding shift_jis -convert html sjis.txt

The MacRoman fallback also explains a question from 2015, textutil convert PDF to txt producing garbled output. The asker's output started %PDF-1.3 followed by %ƒÂÚÂÎßÛ†–ƒ∆. textutil has no PDF reader. On my Korean setting a real PDF is refused. With the MacRoman setting, it read the same PDF as MacRoman text, exited 0, and the second line of the 24,597-byte result was %ƒÂÚÂÎßÛ†–ƒ∆, byte for byte what the asker posted. For text out of a PDF, use pdftotext from poppler, or Preview's export. If you've hit the related "illegal byte sequence" errors with sed and tr, illegal byte sequence on Mac covers the encoding side of that, and pbcopy on Mac shows the same locale fallback breaking the clipboard.

HTML input waits 63 seconds for an image, then fails

When the input is HTML, textutil loads its images and stylesheets. I pointed an <img> at 10.255.255.1, an address that never answers. The conversion to txt sat for 63.2 seconds, printed Timed out while loading attributed string content, wrote nothing and exited 0. With a reachable image on my own site it took 0.8 seconds; with -noload it took 0.08.

-timeout doesn't save the conversion, it only sets how long it waits before failing. With -timeout 1, 3, 10 and 120 the run ended at 1.1, 3.1, 10.1 and 120.1 seconds, each time with a different message from the default run, The file isn’t in the correct format., and each time with no output and exit 0. If you convert HTML you didn't write, especially saved web pages, use -noload. You lose the images either way when the target is txt, docx or doc.

Converting many files: one call, not a loop

I converted 200 copies of a small .docx to txt three ways. One call with a glob took 0.22 seconds. find . -name '*.docx' -exec textutil -convert txt {} + took 0.21. A shell loop calling textutil once per file took 2.21 seconds, about 11 ms per launch. The answer to Argument list too long for textutil conversion uses find -exec ... +, which gets the speed of one call without hitting the argument limit (1,048,576 bytes on this Mac).

# all .docx under a folder to .txt, skipping failures loudly
find ~/docs -name '*.docx' -exec textutil -convert txt {} + 2>errors.log
[ -s errors.log ] && { echo "textutil reported errors:"; cat errors.log; }

Because -output only applies to the first file, sending converted files to another folder needs a loop anyway, as the answer to Output multiple converted files to custom directory shows. At 11 ms a file, that's fine for hundreds of files.

Where textutil questions come from

The Stack Exchange API title search for "textutil" on Stack Overflow, Super User, Ask Different and Unix & Linux returns 15 questions. Five are about TextUtils in Android, Java or Tcl. The other 10 have 16,385 views between them. The biggest, at 10,971 views, is a Linux equivalent of textutil; after that come the garbled PDF (2,499), saving TextEdit documents through AppleScript (671), formatting -excludedelements (647) and the output-directory question (615). Ask Different has none in the title, though it has threads where textutil appears in an answer. Nothing in the 10 is about the docx writer dropping tables, which suggests most people use textutil to get text out, not to produce Word files.

It's one of several small macOS tools I've tested this week with the same blind spot: say returns 0 for voices it doesn't have, plutil saves -bool 1 as false, and textutil reports read failures as success. Check the output, not the exit code.

FAQ

What is textutil on Mac?

textutil is a command-line tool built into macOS since 10.4 that converts documents between txt, rtf, rtfd, html, doc, docx, odt, wordml and webarchive, using the same text system as TextEdit. It can also print file information with -info and join several files into one with -cat. It cannot read or write PDF or Markdown.

Can textutil convert docx to PDF?

No. textutil -convert pdf exits 1 with "Invalid output format." It also can't read PDFs: depending on the account's legacy text encoding it either refuses the file or reads it as MacRoman text and writes gibberish, and both cases exit 0. For docx to PDF, open the file in Pages, Word or TextEdit and export, or use LibreOffice's command line.

Does textutil keep tables when converting to docx?

Not in my tests on macOS 26.4.1. A docx written by textutil had no table, hyperlink, list or image elements; table cells became separate paragraphs and list bullets became typed characters. Converting to odt or rtf kept the table, lists and links, and Word can open both.

Method: all tests ran on 2026-10-08 between 18:00 and 18:15 KST on a Mac mini M4 (Mac16,10, macOS 26.4.1 build 25E253, /usr/bin/textutil 173,088 bytes, man page dated September 9, 2004) in a scratch folder under my work directory. The writer matrix comes from one hand-written HTML file, checked by grepping the output XML for docx, wordml and odt and by converting every output back to HTML. The read tests used four Word-saved files from the python-docx repository and one docx I built by hand; the image result applies to those files and I didn't test documents from Pages. The MacRoman results were produced by setting __CF_USER_TEXT_ENCODING, not on an English-language account, and timings are wall-clock from single runs. Error messages printed in English on this Mac. The Stack Exchange count is from the API title search on the same day, with Android, Java and Tcl questions removed by tag.