Introduction

The tar: Unrecognized archive format error on macOS usually means the downloaded file is not a valid tarball, even if the name ends with .tgz. In TensorFlow tutorial workflows, this often happens when a download command fetched an HTML page, redirect response, or partial file instead of the dataset archive. The fix is to validate file type first, then re-download with proper options.

Confirm the File Is Really a Gzip Tar Archive

Start by inspecting the file before extraction. Extension alone is not reliable.

ls -lh flower_photos.tgz
file flower_photos.tgz

If output says text, HTML, or generic data, the archive is invalid. A correct file should indicate gzip-compressed data.

You can also test gzip integrity directly:

gzip -t flower_photos.tgz && echo "gzip looks valid"

If this fails, extraction will fail as well.

Re-download With Redirect Handling

Many hosting endpoints redirect to signed URLs. If your download tool does not follow redirects, you may save an HTML response body.

Use curl -L or wget with redirect support:

curl -L -o flower_photos.tgz "https://storage.googleapis.com/download.tensorflow.org/example_images/flower_photos.tgz"

Then verify checksum or at least size and file type before unpacking.

file flower_photos.tgz

Once valid, extract:

tar -xzf flower_photos.tgz

Handle Common macOS Tar Variants

macOS ships BSD tar, which works for standard tar.gz files. If extraction still fails but gzip test passes, try listing entries first:

tar -tzf flower_photos.tgz | head

If listing works but extraction fails due to path or permissions, run extraction in a writable directory:

mkdir -p ~/tmp/flowers
cd ~/tmp/flowers
tar -xzf /path/to/flower_photos.tgz

For edge cases, GNU tar from Homebrew can help diagnose differences.

brew install gnu-tar
gtar -xzf flower_photos.tgz

Detect Truncated or Corrupted Downloads

Interrupted downloads produce partial files that still have expected names. Compare local size with expected source size where available.

A quick sanity check:

1python3 - <<'PY'
2import os
3p = 'flower_photos.tgz'
4print('exists:', os.path.exists(p))
5print('size:', os.path.getsize(p) if os.path.exists(p) else 0)
6PY

If size is suspiciously small, delete and re-download. Avoid repeatedly extracting the same corrupted file.

Typical Causes in Tutorial Environments

In notebook or script environments, this error is often caused by one of these:

• stale output file from a failed previous run
• wrong working directory and accidental file overwrite
• corporate proxy returning authentication page
• copied URL that points to a webpage instead of raw file

Inspect the first few bytes to confirm content type:

head -c 80 flower_photos.tgz

If you see HTML markers, the file is not an archive.

Build a Reliable Download and Extract Script

Automating validation avoids recurring data setup failures.

1#!/usr/bin/env bash
2set -euo pipefail
3
4URL="https://storage.googleapis.com/download.tensorflow.org/example_images/flower_photos.tgz"
5FILE="flower_photos.tgz"
6
7curl -L --fail -o "$FILE" "$URL"
8file "$FILE"
9gzip -t "$FILE"
10mkdir -p data
11tar -xzf "$FILE" -C data
12
13echo "dataset extracted to data/"

This script fails early if the download is not a valid gzip tarball.

Common Pitfalls

• Trusting file extension instead of checking real file type.
• Downloading without redirect support and saving HTML response pages.
• Retrying extraction without deleting corrupted partial files.
• Ignoring proxy-auth or firewall pages masquerading as dataset files.
• Running extraction in unwritable directories and misreading resulting errors.

Summary

• The error usually indicates invalid file content, not a tar command bug.
• Verify archive integrity with file and gzip -t before extracting.
• Re-download using redirect-aware commands such as curl -L.
• Use scripted validation to make tutorial data setup repeatable.
• Check for truncated files, proxy responses, and wrong URLs when issues persist.