Install depth-anything.cpp on macOS: Local Depth Maps from One Photo

⬅️ Back to Tutorials

A photo is flat. A depth map tells you which pixels sit closer and which sit farther. That is enough for messy cutouts, cheap parallax, a rough point cloud, or a focus effect, without a stereo camera or LiDAR.

depth-anything.cpp is a C++17/ggml port of Depth Anything 3. It is a CLI you run on your own machine. No Ollama. No PyTorch. On a Mac I went from empty folder to first PNG in about twenty minutes.

TLDR:

You want relative depth from one RGB image, offline, on Apple Silicon.
Clone with --recursive, then build CPU Release (DA_GGML_METAL=OFF on my M2).
Put depth-anything-base-q4_k.gguf (~99MB) in models/.
Run da3-cli depth ... --png out.png. The flag is --png, not --out.
Metal segfaulted on me (exit 139). CPU finished.

Prerequisites: macOS on Apple Silicon, plus git, cmake, clang++ (Xcode CLT), and either curl or the hf CLI.

Why bother

Monocular depth is an educated guess. One JPG does not contain real meters. The model still produces a near/far field that is useful for a lot of day-to-day work: pull a subject off a busy background, feed parallax into an editor, export --glb or a reconstruct/--ply mesh once you move to larger weights, or prototype perception code without buying a depth sensor. And the photo never leaves disk.

It will not replace a tape measure. The PNG is relative depth (farther usually looks lighter in the default export). True metric scale needs the nested/metric GGUFs and a different setup. Use BASE first. If the images look sane, then chase metric.

I reached for the C++ port instead of a notebook because ggml plus one binary means one compile, one weight file, and no torch/CUDA dependency fight. Local chat apps will not load these GGUFs. Think of da3-cli the way you think of ffmpeg: you call it, you get a file, you move on.

Step 1: Clone the repo

cd ~/Documents
git clone --recursive https://github.com/mudler/depth-anything.cpp
cd depth-anything.cpp

You should see third_party/ggml on disk. If you forgot --recursive, the build will fail later. Fix with git submodule update --init --recursive.

Step 2: Build the CLI (CPU)

cmake -B build -DCMAKE_BUILD_TYPE=Release -DDA_BUILD_CLI=ON -DDA_GGML_METAL=OFF
cmake --build build -j

When it works, build/examples/cli/da3-cli exists. I tried -DDA_GGML_METAL=ON first. Metal came up, weights moved to the GPU, then the process died with exit 139. CPU ran clean. Stay on CPU until Metal works on your box.

Step 3: Download DA3-BASE weights

mkdir -p models
curl -L --fail -o models/depth-anything-base-q4_k.gguf \
  "https://huggingface.co/mudler/depth-anything.cpp-gguf/resolve/main/depth-anything-base-q4_k.gguf"
ls -lh models/depth-anything-base-q4_k.gguf

Or: hf download mudler/depth-anything.cpp-gguf depth-anything-base-q4_k.gguf --local-dir models.

You want a file around 99MB. Q4_K BASE is the right first download: small, fast, good enough to decide if this tool fits your photos. Bigger and metric variants sit in the same Hugging Face repo when you need them.

Step 4: Run a test photo

./build/examples/cli/da3-cli depth \
  --model models/depth-anything-base-q4_k.gguf \
  --input ~/Downloads/your-photo.jpg \
  --png ./depth.png

I got a line like depth 378x504 min=0.5225 max=1.6810 and a depth.png next to the command. Your size and range will differ. Open the PNG beside the source. You want a coherent near/far field, not salt-and-pepper noise.

Floating point for code: add --pfm depth.pfm. 3D: try --glb or reconstruct after BASE looks right on your domain.

Pro tip: leave the binary and GGUF in the build tree. There is no app-store install. You keep calling the same two paths.

Cleanup

Nothing to uninstall. Drop the clone if you are done:

rm -rf ~/Documents/depth-anything.cpp

If it breaks:

unknown flag: --out means you wanted --png or --pfm.
Exit 139 after Metal init: rebuild with -DDA_GGML_METAL=OFF.
Missing ggml: re-clone with --recursive, or init the submodules.