How to Write Cross-Platform Compatible Bash Scripts

Understanding Cross-Platform Challenges
Start with a Portable Shebang Line
Core Utilities: GNU vs. BSD Differences
Path Handling and File System Quirks
Environment Variables and OS-Specific Behavior
Conditional Checks and OS Detection
Avoiding Bash-Specific Pitfalls
Testing and Validation
Best Practices for Portability
Example: A Cross-Platform Bash Script
Conclusion
References

1. Understanding Cross-Platform Challenges

Before diving into solutions, it’s critical to recognize the primary sources of incompatibility:

Shell Versions

Linux: Most modern Linux distros ship with bash 4.x or 5.x (e.g., Ubuntu 22.04 uses bash 5.1).
macOS: Defaults to zsh (since Catalina), but bash is still available (usually version 3.2, due to licensing restrictions).
WSL: Behaves like Linux (uses GNU utilities), but may interact with Windows file systems.
BSD: Uses BSD-based shells and utilities (e.g., FreeBSD’s bash is optional and often outdated).

Core Utilities

Unix-like systems rely on “core utilities” (e.g., sed, grep, date, find), but these vary between:

GNU: Used by Linux and WSL (feature-rich, with extended flags like sed -i for in-place editing).
BSD: Used by macOS and BSD systems (syntax differences, e.g., sed -i '' requires a backup flag).

File System Differences

Case sensitivity: Linux/BSD are case-sensitive; macOS (APFS) is case-insensitive by default.
Path separators: Unix uses /, Windows uses \ (relevant in WSL).
Line endings: Windows uses \r\n, Unix uses \n (can break scripts if not handled).

2. Start with a Portable Shebang Line

The shebang line (#!) tells the OS which interpreter to use. For portability:

Use `#!/usr/bin/env bash` Instead of `#!/bin/bash`

#!/bin/bash hardcodes the path to bash, which may not exist (e.g., macOS bash is in /bin/bash, but some systems use /usr/local/bin/bash).
#!/usr/bin/env bash uses the env command to locate bash in the user’s $PATH, making it more portable.

Caveat: env isn’t available on all systems (e.g., very old Unix), but it’s standard on Linux, macOS, and WSL.

3. Core Utilities and Command Differences

Many commands behave differently between GNU and BSD. Here’s how to handle common ones:

`sed` In-Place Editing

GNU sed -i edits files in-place without backups:

sed -i 's/old/new/g' file.txt  # GNU (Linux/WSL)

BSD sed -i requires a backup suffix (use '' for no backup):

sed -i '' 's/old/new/g' file.txt  # BSD (macOS)

Portable Fix: Use a function to detect the OS and adjust the flag:

sed_inplace() {
  if [[ "$OSTYPE" == "darwin"* ]]; then
    sed -i '' "$@"  # macOS/BSD
  else
    sed -i "$@"     # Linux/WSL
  fi
}
# Usage: sed_inplace 's/old/new/g' file.txt

`date` Formatting

GNU date supports -d for arbitrary dates (e.g., date -d "2 days ago").
BSD date uses -j -f (e.g., date -j -f "%Y-%m-%d" "2024-01-01" +"%Y%m%d").

Portable Fix: Avoid complex date logic, or use a helper function:

get_current_date() {
  if [[ "$OSTYPE" == "darwin"* ]]; then
    date +"%Y-%m-%d"  # BSD date
  else
    date +"%Y-%m-%d"  # GNU date (same format here, but adjust for complexity)
  fi
}

`grep` and Regular Expressions

Use grep -E instead of egrep (some systems deprecate egrep).
Avoid GNU-specific flags like --color or -P (Perl regex).

`find` Command

GNU find has -maxdepth, -exec +, and -print0; BSD find supports these but may have syntax nuances. Stick to POSIX-compliant flags like -name, -type, and -exec \;.

4. Path Handling and File System Quirks

Use `/` for Paths, Avoid Backslashes

Always use forward slashes (/), even in WSL (Windows paths like C:\Users can be accessed via /mnt/c/Users in WSL).

Avoid OS-Specific Absolute Paths

Bad: Hardcoding /home/user (Linux) or /Users/user (macOS).
Good: Use $HOME (works everywhere) or ~ (expands to $HOME).

Handle Spaces and Special Characters

Always quote variables to avoid breaking paths with spaces:

file="my document.txt"
cat "$file"  # Good (quotes prevent word-splitting)
# cat $file  # Bad (splits into "my" and "document.txt")

Line Endings: Use `dos2unix` (If Needed)

If your script is edited on Windows, convert line endings to Unix-style with dos2unix script.sh to avoid \r causing syntax errors.

5. Environment Variables and OS-Specific Behavior

Use Standardized Variables

$HOME: User’s home directory (works everywhere).
$PATH: Executable search path (avoid hardcoding additions; append with export PATH="$PATH:/new/dir").
$USER or $LOGNAME: Current user (prefer $USER, more widely supported).

Avoid OS-Specific Variables

Linux: $XDG_CONFIG_HOME (user configs), but macOS uses $HOME/Library/Application Support.
Use cross-platform paths like $HOME/.config instead of OS-specific locations.

6. Conditional Checks and OS Detection

Use $OSTYPE or uname -s to detect the OS and adjust behavior:

Detect macOS

if [[ "$OSTYPE" == "darwin"* ]]; then
  echo "Running on macOS"
  # Use BSD commands here
fi

Detect Linux

if [[ "$OSTYPE" == "linux-gnu"* ]]; then
  echo "Running on Linux/WSL"
  # Use GNU commands here
fi

Detect WSL

WSL sets $WSL_DISTRO_NAME (WSL 2) or $IS_WSL (older versions):

if [[ -n "$WSL_DISTRO_NAME" || -n "$IS_WSL" ]]; then
  echo "Running on WSL"
  # Handle Windows file system interactions
fi

Check for Command Existence

Use command -v to verify required tools exist before using them:

if ! command -v jq &> /dev/null; then
  echo "Error: jq is required but not installed." >&2
  exit 1
fi

7. Avoiding Bash-Specific Pitfalls

Limit Bash Features to Ensure Compatibility

Associative Arrays: Added in bash 4.0 (macOS bash 3.2 lacks them). Avoid or check bash version:

if [[ ${BASH_VERSINFO[0]} -lt 4 ]]; then
  echo "Error: Bash 4.0+ required." >&2
  exit 1
fi

Process Substitution: <(command) works in bash but may fail in POSIX sh. Use temporary files instead for portability.

Use `set -euo pipefail` for Robustness

Add this at the top of your script to catch errors early:

-e: Exit on any command failure.
-u: Treat unset variables as errors.
-o pipefail: Exit if any command in a pipeline fails.

#!/usr/bin/env bash
set -euo pipefail  # Makes scripts safer and more predictable

8. Testing and Validation

Use `shellcheck` for Static Analysis

ShellCheck is a linter that flags portability issues (e.g., non-POSIX flags, undefined variables). Install it and run:

shellcheck script.sh

Test Across OSes

Linux: Use Docker (e.g., ubuntu, alpine for musl libc).
macOS: Use a physical machine, VM, or GitHub Actions (macOS runners).
WSL: Test in a Windows VM with WSL enabled.
BSD: Use a FreeBSD VM or Docker image (e.g., freebsd:latest).

Test with Older Bash Versions

To mimic macOS bash 3.2, use Docker:

docker run -it --rm bash:3.2 sh  # Test script in bash 3.2

9. Best Practices for Portability

Keep It Simple: Avoid obscure bash features (e.g., process substitution, associative arrays) unless necessary.
Comment Complex Logic: Explain OS-specific workarounds for future maintainers.
Use Functions for Reusability: Wrap OS-dependent code in functions (e.g., sed_inplace above).
Version Check Early: If your script requires bash 4+, check $BASH_VERSION at the start.
Document Dependencies: List required tools (e.g., jq, curl) in comments or a README.

10. Example: A Cross-Platform Bash Script

Here’s a sample script demonstrating portability best practices:

#!/usr/bin/env bash
set -euo pipefail

# Check for required bash version (minimum 3.2)
if [[ ${BASH_VERSINFO[0]} -lt 3 || (${BASH_VERSINFO[0]} -eq 3 && ${BASH_VERSINFO[1]} -lt 2) ]]; then
  echo "Error: Bash 3.2+ is required." >&2
  exit 1
fi

# Detect OS and set sed in-place flag
detect_sed_inplace() {
  if [[ "$OSTYPE" == "darwin"* ]]; then
    echo "-i ''"  # BSD/macOS requires backup flag ('' = no backup)
  else
    echo "-i"     # GNU/Linux/WSL
  fi
}
SED_INPLACE=$(detect_sed_inplace)

# Example: Replace "old" with "new" in a file
file="example.txt"
echo "old" > "$file"
eval "sed $SED_INPLACE 's/old/new/g' \"$file\""  # Use eval to handle SED_INPLACE with spaces

# Cleanup
rm -f "$file"

echo "Script ran successfully on $(uname -s)!"

11. Conclusion

Writing cross-platform bash scripts requires awareness of OS differences, careful command selection, and rigorous testing. By using portable shebangs, handling core utility quirks, and validating across environments, you can ensure your scripts work reliably on Linux, macOS, WSL, and beyond.

Remember: simplicity and testing are your best tools. When in doubt, use POSIX-compliant syntax and avoid OS-specific features.

Table of Contents