Writing Cross-Platform Shell Scripts: Tips and Strategies

Understanding Platform Differences
Core Strategies for Cross-Platform Compatibility
Practical Tips with Code Examples
Best Practices for Maintainable Cross-Platform Scripts
Conclusion
References

Understanding Platform Differences

Before diving into solutions, it’s critical to recognize the key differences that break shell scripts across platforms. Below are the most common pitfalls:

1.1 Shell Environments: Bash, PowerShell, and cmd.exe

The primary shell varies by OS:

Linux: Typically Bash (Bourne-Again Shell) or Zsh (default on newer macOS).
macOS: Zsh (default since 2019) or Bash (older versions).
Windows: PowerShell (modern, cross-platform) or legacy cmd.exe.

Syntax differences between shells are profound. For example, variable expansion ($VAR in Bash vs. %VAR% in cmd.exe or $env:VAR in PowerShell), loop structures, and command substitution ($(command) in Bash/PowerShell vs. `command` in legacy shells) can derail scripts.

1.2 Line Endings and File Format

Windows uses CRLF (\r\n) line endings, while Unix-like systems (Linux/macOS) use LF (\n). Mismatched line endings can cause scripts to fail (e.g., bash: syntax error near unexpected token $‘\r’`). Most modern editors (VS Code, Vim) and version control tools (Git) can auto-convert line endings, but this remains a common gotcha.

1.3 Path Separators and Filesystem Conventions

Unix-like: Uses forward slashes (/), e.g., /home/user/documents.
Windows: Uses backslashes (\), e.g., C:\Users\user\Documents. Backslashes also act as escape characters in Unix shells, complicating cross-platform path handling.

1.4 Command Availability and Behavior

Common commands often differ in name or functionality:

Listing directories: ls (Unix) vs. dir (Windows cmd.exe).
Finding text: grep (Unix) vs. Select-String (PowerShell).
Process management: ps aux (Unix) vs. Get-Process (PowerShell).

Even “standard” commands like sed or awk may have OS-specific extensions (e.g., BSD sed on macOS vs. GNU sed on Linux).

1.5 Environment Variables and Expansion

Unix: Variables are referenced with $VAR (e.g., $HOME), and exported with export VAR=value.
Windows cmd.exe: Variables use %VAR% (e.g., %USERPROFILE%), and are set with set VAR=value.
PowerShell: Variables use $env:VAR (e.g., $env:USERPROFILE), and are set with $env:VAR = "value".

1.6 File Permissions and Execution

Unix-like systems use file permissions (e.g., chmod +x script.sh) to control execution, while Windows relies on file extensions (.bat, .ps1) and execution policies (e.g., Set-ExecutionPolicy RemoteSigned for PowerShell).

Core Strategies for Cross-Platform Compatibility

To write shell scripts that work across OSes, adopt one or more of these foundational strategies:

2.1 Target a Common Shell

Choose a shell that runs on all target OSes. The most popular options are:

Bash: Available on Linux, macOS, and Windows (via WSL, Git Bash, or Cygwin). Use POSIX-compliant Bash to maximize compatibility.
PowerShell Core (pwsh): Microsoft’s cross-platform shell, available natively on Windows, Linux, and macOS. Ideal if your audience already uses PowerShell.

Tradeoff: Bash is ubiquitous in Unix environments but requires Windows users to install additional tools. PowerShell avoids this but may be unfamiliar to Unix-centric users.

2.2 Leverage Cross-Platform Tools and Languages

For complex workflows, consider replacing shell scripts with higher-level languages like Python, Node.js, or Go. These languages provide built-in cross-platform APIs for paths, environment variables, and process execution (e.g., Python’s os.path module or Node.js’s path module).

Example: A Python script to list files (works everywhere):

import os

for file in os.listdir("."):
    print(file)

2.3 Use Conditional Checks for Platform-Specific Logic

Detect the OS or shell at runtime and branch logic accordingly. For example, run ls on Unix and dir on Windows, or use grep vs. Select-String.

2.4 Standardize on POSIX-Compliant Utilities

Stick to POSIX-compliant commands and syntax to ensure compatibility across Unix-like shells (Bash, Zsh, Dash). Avoid non-POSIX extensions (e.g., Bash arrays, read -d, or process substitution with <(command)).

Practical Tips with Code Examples

Let’s dive into actionable tips with code snippets to address common cross-platform challenges.

3.1 Detecting the Operating System

Identify the OS at runtime to branch platform-specific logic.

Bash Example: Detect OS with `uname`

#!/usr/bin/env bash

# Detect OS using uname (works on Linux, macOS, Cygwin, Git Bash)
case "$(uname -s)" in
    Linux*)     OS="Linux";;
    Darwin*)    OS="macOS";;
    CYGWIN*)    OS="Cygwin";;  # Cygwin on Windows
    MINGW*)     OS="MinGW";;   # Git Bash on Windows
    *)          OS="Unknown";;
esac

echo "Detected OS: $OS"

# Example: Use OS-specific command to list directories
if [ "$OS" = "Linux" ] || [ "$OS" = "macOS" ] || [ "$OS" = "Cygwin" ] || [ "$OS" = "MinGW" ]; then
    ls -la
else
    echo "Unsupported OS"
    exit 1
fi

PowerShell Example: Detect OS with `$Env:OS`

# Detect OS (PowerShell)
if ($Env:OS -eq "Windows_NT") {
    $OS = "Windows"
} elseif ($Env:OSTYPE -eq "linux-gnu") {
    $OS = "Linux"
} elseif ($Env:OSTYPE -eq "darwin") {
    $OS = "macOS"
} else {
    $OS = "Unknown"
}

Write-Host "Detected OS: $OS"

# Example: List directories
if ($OS -eq "Windows") {
    dir
} else {
    ls -la
}

3.2 Handling File Paths Consistently

Use forward slashes (/) for paths whenever possible—most modern Windows shells (WSL, Git Bash, PowerShell) accept / as a path separator. For Windows cmd.exe, use conditional logic.

Example: Cross-Platform Paths in Bash

#!/usr/bin/env bash

# Use forward slashes for paths (works in WSL/Git Bash/Cygwin on Windows)
DATA_DIR="./data"
LOG_FILE="$DATA_DIR/app.log"

# Create directory (mkdir -p works cross-platform in Bash)
mkdir -p "$DATA_DIR"

# Write to log (works everywhere)
echo "Script started at $(date)" > "$LOG_FILE"

Example: Path Conversion for Windows `cmd.exe`

If targeting cmd.exe, use backslashes conditionally:

#!/usr/bin/env bash

if [ "$(uname -s)" = "MINGW64_NT" ] || [ "$(uname -s)" = "CYGWIN_NT" ]; then
    # Convert to Windows-style path (Git Bash/Cygwin)
    DATA_DIR="$(cygpath -w ./data)"  # Uses cygpath to convert / to \
else
    DATA_DIR="./data"
fi

mkdir -p "$DATA_DIR"

3.3 Managing Environment Variables

Use tools like cross-env (for Node.js projects) to standardize environment variable handling across OSes. For standalone scripts, detect the shell and use compatible syntax.

Example: `cross-env` for Node.js Projects

cross-env abstracts OS-specific variable syntax. Install it via npm:

npm install --save-dev cross-env

Use it in package.json scripts:

{
  "scripts": {
    "start": "cross-env NODE_ENV=production node server.js"
  }
}

This runs NODE_ENV=production node server.js on Unix and set NODE_ENV=production && node server.js on Windows cmd.exe.

3.4 Shebang Line Best Practices

The shebang line (#!/path/to/shell) specifies the script’s interpreter. Use #!/usr/bin/env bash instead of #!/bin/bash to ensure the system uses the user’s bash (which may be in a non-standard location, e.g., /usr/local/bin/bash on macOS).

#!/usr/bin/env bash  # Portable shebang

3.5 Avoid Non-POSIX Shell Features

Stick to POSIX-compliant syntax to ensure compatibility with older shells (e.g., Dash on Debian/Ubuntu). Avoid Bash-specific features like:

Arrays (my_array=(1 2 3)).
Process substitution (<(command)).
read -d (use while IFS= read -r line instead for line-by-line reading).

Example: POSIX-Compliant Line Reading

#!/usr/bin/env sh  # Use POSIX sh instead of bash

# POSIX-compliant line reading (works in all shells)
while IFS= read -r line; do
    echo "Line: $line"
done < "input.txt"

3.6 Use Cross-Platform Command Alternatives

Replace OS-specific commands with tools that work everywhere. For example:

Use find (Unix) vs. Get-ChildItem (PowerShell), or adopt fd (a cross-platform find alternative).
Use rg (ripgrep) instead of grep for consistent text searching.

Best Practices for Maintainable Cross-Platform Scripts

4.1 Test Across Multiple Environments

Test scripts on all target OSes:

Linux: Use Docker (e.g., docker run -v $(pwd):/scripts ubuntu /scripts/script.sh).
macOS: Use a physical machine or virtual machine (e.g., Parallels).
Windows: Use WSL, Git Bash, PowerShell, and cmd.exe (if supported).

4.2 Keep It Simple and Readable

Avoid overly complex logic. If a script requires dozens of conditional checks, consider migrating to Python/Node.js. Use descriptive variable names and comments to clarify platform-specific code.

4.3 Document Dependencies and Requirements

Explicitly state prerequisites (e.g., “Requires Bash 4.0+, WSL, or Git Bash on Windows”). Include setup instructions for Windows users (e.g., “Install Git Bash from https://git-scm.com/“).

4.4 Use Linting and Static Analysis Tools

Tools like shellcheck (for Bash) or PSScriptAnalyzer (for PowerShell) catch cross-platform issues early:

# Install shellcheck (Linux/macOS)
sudo apt install shellcheck  # Debian/Ubuntu
brew install shellcheck      # macOS

# Lint a script
shellcheck script.sh

4.5 Version Control and Iterative Testing

Store scripts in version control (Git) and track platform-specific fixes. Use feature branches to test changes on target OSes before merging.

4.6 Handle Errors Gracefully

Use set -euo pipefail in Bash to exit on errors, undefined variables, or pipeline failures:

#!/usr/bin/env bash
set -euo pipefail  # Exit on error, undefined variable, or pipeline failure

# Fails fast if "data" directory is missing
cp "$DATA_DIR/file.txt" ./backup/

Conclusion

Writing cross-platform shell scripts requires awareness of OS differences, strategic tooling, and disciplined testing. By targeting a common shell (e.g., Bash), using conditional logic, and leveraging cross-platform tools, you can create scripts that automate workflows seamlessly across Linux, macOS, and Windows.

For simple tasks, POSIX-compliant Bash with WSL/Git Bash support on Windows is often sufficient. For complex workflows, consider higher-level languages like Python or Node.js, which abstract OS-specific details. Always test rigorously and document requirements to ensure a smooth experience for users across platforms.

Table of Contents