Zsh: Permission Denied When Using Flutter Commands (flutter doctor, upgrade)? Fix Guide for .zshrc & PATH Issues

If you’ve switched to Zsh (Z shell) for its powerful features like auto-completion, themes, and plugins, you might have encountered a frustrating error when running Flutter commands: zsh: permission denied: flutter. This error typically arises when Zsh can’t properly locate the Flutter SDK or lacks the necessary permissions to execute its binaries.

Whether you’re trying to run flutter doctor, flutter upgrade, or any other Flutter command, this guide will walk you through diagnosing and fixing the root causes—most often misconfigurations in your .zshrc file or issues with your system’s PATH environment variable. By the end, you’ll have a clear understanding of how Zsh interacts with Flutter and how to resolve permission-related roadblocks.

Table of Contents#

  1. Understanding the "Permission Denied" Error
  2. Common Causes of the Error
  3. Step-by-Step Fix Guide
  4. Advanced Troubleshooting
  5. Conclusion
  6. References

Understanding the "Permission Denied" Error#

When Zsh throws zsh: permission denied: flutter, it means one of two things:

  • Zsh cannot find the flutter executable (due to a misconfigured PATH), OR
  • Zsh found the executable but lacks the permissions to run it (due to file/directory permission issues).

This error is distinct from zsh: command not found: flutter, which indicates the flutter binary isn’t in your PATH at all. Here, "permission denied" suggests Zsh found the binary but can’t execute it—often due to incorrect file permissions or a PATH pointing to a restricted directory.

Common Causes of the Error#

Before diving into fixes, let’s identify the most likely culprits:

  1. Incorrect PATH Entry in .zshrc:
    The PATH environment variable tells Zsh where to look for executables. If your Flutter SDK’s bin directory isn’t in PATH, or is misconfigured (e.g., pointing to the parent flutter folder instead of flutter/bin), Zsh can’t find the flutter command.

  2. Missing Execute Permissions on Flutter Binaries:
    The flutter executable (located in flutter/bin/flutter) must have "execute" permissions (chmod +x) to run. Without this, even if PATH is correct, Zsh will deny access.

  3. .zshrc Not Sourced After Changes:
    If you modified .zshrc but forgot to reload it (with source ~/.zshrc), Zsh won’t recognize the updated PATH.

  4. Flutter Installed in a Restricted Directory:
    Installing Flutter in system directories like /usr/local/ or /opt/ without proper permissions (e.g., using sudo for installation but not for execution) can cause permission issues.

  5. Typos or Syntax Errors in .zshrc:
    A missing colon, extra space, or typo (e.g., fluter instead of flutter) in the PATH entry will break the configuration.

Step-by-Step Fix Guide#

Let’s resolve the error with a systematic approach.

Step 1: Locate Your Flutter Installation Path#

First, confirm where your Flutter SDK is installed. This is critical for verifying the PATH entry.

How to Find the Path:#

  • Check PATH for existing entries: Run echo $PATH to see if Flutter’s bin directory is listed. Look for paths like /home/yourusername/flutter/bin or /Users/yourusername/flutter/bin.
  • If PATH doesn’t show it: Use which flutter to locate the executable. If this returns flutter: command not found, search manually: 
    # Search your home directory for the Flutter SDK
find ~ -name "flutter" -type d | grep "flutter$"
    Common install locations: ~/flutter, ~/development/flutter, or ~/Documents/flutter.

Step 2: Verify .zshrc Configuration#

The .zshrc file (located in your home directory: ~/.zshrc) is where Zsh loads environment variables like PATH. Let’s check for Flutter-related entries.

Steps:#

  1. Open .zshrc with a text editor (e.g., nano, vim, or VS Code): 
    nano ~/.zshrc
  2. Search for PATH entries. Look for lines like: 
    export PATH="$PATH:/path/to/flutter/bin"  # Correct: points to flutter/bin
export PATH="$PATH:/path/to/flutter"      # Incorrect: missing /bin
    The correct entry must point to the bin subdirectory of your Flutter SDK (e.g., ~/flutter/bin), not the parent flutter folder.

Step 3: Update PATH in .zshrc#

If the PATH entry is missing or incorrect, add/modify it.

Example Fix:#

Suppose your Flutter SDK is installed at ~/flutter. Add this line to .zshrc (replace ~/flutter with your actual path):

export PATH="$PATH:$HOME/flutter/bin"  # $HOME is shorthand for /home/yourusername

Save and Reload .zshrc:#

  • In nano, press Ctrl+O to save, then Ctrl+X to exit.
  • Reload .zshrc to apply changes immediately: 
    source ~/.zshrc

Step 4: Fix File Permissions for Flutter Binaries#

If PATH is correct but you still get "permission denied," the flutter executable likely lacks execute permissions.

Check Permissions:#

Run this command to inspect the flutter binary’s permissions (replace /path/to/flutter with your SDK path):

ls -la /path/to/flutter/bin/flutter

You should see output like:

-rwxr-xr-x 1 yourusername yourusername 12345 Jun 1 12:00 flutter

The first three characters (rwx) indicate the owner has read, write, and execute permissions. If you see -rw-r--r-- (no x), execute permissions are missing.

Add Execute Permissions:#

Run:

chmod +x /path/to/flutter/bin/flutter

For good measure, ensure the entire flutter/bin directory has traversal permissions:

chmod +rx /path/to/flutter/bin  # +r (read) and +x (execute/traverse)

Step 5: Test the Fix#

Run flutter doctor to verify:

flutter doctor

If successful, you’ll see Flutter’s diagnostic output. If not, proceed to advanced troubleshooting.

Advanced Troubleshooting#

If the error persists, try these fixes:

1. Check for Conflicting .zsh* Files#

Zsh loads configuration from multiple files (e.g., .zshenv, .zprofile, .zshrc). A later file might overwrite your PATH entry.

  • List all Zsh config files: 
    ls -la ~/ | grep ".zsh"
  • Check .zprofile or .zshenv for conflicting PATH entries and remove duplicates.

2. Ensure You Own the Flutter Directory#

If Flutter is installed in a directory owned by root (e.g., /usr/local/flutter), you may lack permissions. Change ownership to your user:

sudo chown -R $USER:$USER /path/to/flutter

3. Move Flutter to a User Directory#

Avoid system directories like /opt/ or /usr/local/ for Flutter. Installing in your home directory (~/flutter) ensures you have full permissions without sudo.

4. Use strace to Diagnose Permission Issues#

For advanced debugging, trace system calls to see where the "permission denied" occurs:

strace flutter doctor 2>&1 | grep "permission denied"

This will show the exact file/directory causing the error (e.g., a missing dart executable in flutter/bin/cache/dart-sdk/bin).

Conclusion#

"Permission denied" errors with Flutter in Zsh are almost always due to PATH misconfiguration, missing execute permissions, or restricted install directories. By verifying your .zshrc PATH entry, ensuring the flutter binary has execute permissions, and installing Flutter in a user-owned directory, you can resolve the issue quickly.

Remember to source .zshrc after edits and test with flutter doctor to confirm success.

References#

2026-01