When Zsh breaks, guessing is slow. Debug logging tells you the truth. You see every command, every variable, every expansion. No magic. No mystery. Just raw signals from the shell as it runs.
To turn on debug logging in Zsh, set the xtrace option. This prints each command before it runs:
set -x
# your code here
set +x
For deeper visibility, use setopt ERR_EXIT to stop on the first error, and setopt WARN_CREATE_GLOBAL to track unintended variables. Combine it with PS4 to format debug output:
export PS4='+ ${ZSH_NAME}:${LINENO}: '
set -x
Now Zsh will log with file and line numbers. Pair this with output redirection to capture logs for later analysis:
set -x
exec 2>zsh-debug.log
# script content
exec 2>&2
set +x
This creates a complete trace of your script execution. You can grep logs, pinpoint bottlenecks, and locate silent failures. With trap '...' DEBUG, you can run custom logging on every command without editing your script flow.
Debug logging in Zsh is not just for fixing broken scripts. It’s for understanding them. It’s for running code with evidence. Long pipelines, complex functions, interactive jobs—each line written down as it happens. Your future self will thank you.
The faster you see the truth, the faster you ship. And the fastest way to wire this kind of insight into your workflow is with tools that show you live output in context. Hoop.dev lets you see it in minutes. Try it, connect your environment, and watch your Zsh debug logs stream as you work.