Run Swift Packages on Linux Using Your Mac

Swift runs on Linux, but most developers discover compatibility issues only when GitHub Actions fail. Use act to run GitHub Actions workflows locally and catch Linux issues before pushing.

Prerequisites

• Homebrew installed
• Docker Desktop running
• GitHub Actions workflow in .github/workflows/

Install act

brew install act

First run prompts for Docker image selection:

act

> ? Please choose the default image you want to use with act:
>   - Large size image: +20GB Docker image, includes almost all tools used on GitHub Actions (IMPORTANT: currently only ubuntu-18.04 platform is available)
>   - Medium size image: ~500MB, includes only necessary tools to bootstrap actions and aims to be compatible with all actions
>   - Micro size image: <200MB, contains only NodeJS required to bootstrap actions, doesn't work with all actions

Choose Medium for Swift workflows.

Create a Workflow

Example .github/workflows/test-linux.yml:

name: Linux Tests

on: [push, pull_request]

jobs:
  test-linux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: swift-actions/setup-swift@v2
        with:
          swift-version: "5.9"
      - name: Build
        run: swift build
      - name: Run tests
        run: swift test

Run Locally

Execute all workflows:

act

> [Linux Tests/test-linux] 🚀  Start image=catthehacker/ubuntu:act-latest
> [Linux Tests/test-linux]   🐳  docker pull image=catthehacker/ubuntu:act-latest platform= username= forcePull=true
> [Linux Tests/test-linux]   🐳  docker create image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[]
> [Linux Tests/test-linux]   🐳  docker run image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[]
> [Linux Tests/test-linux] ⭐ Run Main actions/checkout@v4
> [Linux Tests/test-linux]   🧰  Checkout
> [Linux Tests/test-linux] ⭐ Run Main swift-actions/setup-swift@v2
> [Linux Tests/test-linux]   ✅  Success - Main swift-actions/setup-swift@v2
> [Linux Tests/test-linux] ⭐ Run Main Build
> | Building for production...
> [Linux Tests/test-linux]   ✅  Success - Main Build
> [Linux Tests/test-linux] ⭐ Run Main Run tests
> | Test Suite 'All tests' passed
> [Linux Tests/test-linux]   ✅  Success - Main Run tests

Run Specific Jobs

# Run specific workflow
act -W .github/workflows/test-linux.yml

# Run specific job
act -j test-linux

# Run with verbose output
act -v

Troubleshooting

Docker not running:

act

> Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Start Docker Desktop first.

Swift version mismatch: Update swift-version in workflow to match your SPM requirements.

Platform-specific code fails: Use #if os(Linux) preprocessor directives:

#if os(Linux)
import Glibc
#else
import Darwin
#endif

When to Use

• Before pushing: Validate Linux compatibility locally
• CI debugging: Reproduce GitHub Actions failures
• Multi-platform testing: Test both macOS and Linux builds
• MCP server development: Ensure cross-platform Swift tools work

Limitations

• Runs in Docker container (slight performance overhead)
• Requires Docker Desktop installation
• Some GitHub Actions features unsupported
• Cannot test macOS-specific frameworks

For macOS-only features (SwiftUI, UIKit), use native testing. For command-line tools and server applications, act catches Linux issues before CI.