Run single-file Swift scripts with package dependencies declared inline.
Overview · Quick look · Install · Usage · Requirements · Documentation · Contributing · License
Keep a script in one file, with no Package.swift to maintain. A trailing import comment names a dependency; swift sh builds the generated package in a cache and forwards your arguments. See dependency comments and the command reference for syntax and execution rules.
Increment a version with SemVer:
Install with Homebrew from the swift-library tap:
brew install swift-library/tap/swift-shThe formula builds swift-sh from its release source, so Swift 6.3 or later
must be on PATH. On macOS, select Xcode 26.6 or later with xcode-select.
To build from source instead:
git clone --branch v0.2.0 https://github.com/swift-library/swift-sh.git
cd swift-sh
swift build -c release --force-resolved-versionsCopy .build/release/swift-sh to a directory on your PATH, then check the
installation with swift sh --version.
Note
swift-sh is pre-1.0. Minor releases may include breaking changes to its commands and dependency comment syntax.
Save a Swift file with a package comment after each dependency import, then run
swift sh version.swift 1.2.3. Arguments after the file path go to the script;
standard streams, working directory, and exit status are preserved.
The dependency reference covers repository forms, version constraints, and import discovery. The command reference covers standard input, debug builds, packaging, editing, caching, and execution limits.
- Swift 6.3 or later on
PATH, for both swift-sh and the scripts it builds - macOS 15 or later, or Linux with a supported Swift toolchain
- On macOS, building swift-sh requires the macOS SDK from Xcode 26.6 or later
Each release supports the three most recent major macOS versions, currently macOS 15, 26, and 27. Shared macOS CI builds and tests with Xcode 26.6 on macOS 26; the latest SDK checks availability for older supported systems at compile time. Linux CI uses the Swift 6.3.3 Ubuntu 24.04 container on Ubuntu 24.04 runners. The release reference records release facts and mechanics; version rules are in VERSIONING.
- Command reference: input handling, packaging, editing, the cache, path rules, and exit codes.
- Dependency comments: every repository form, version constraint, and conditional compilation rule.
- Runtime architecture: script analysis, generated packages, caching, and execution.
- Example scripts: terminal colors, Swift Markdown, and an async entry point.
- Changelog
Read CONTRIBUTING.md for the build, test, and formatting commands to run before opening a pull request. Report vulnerabilities through the private route in SECURITY.md.
swift-sh is available under the Apache License 2.0 with the Swift Runtime Library Exception. See LICENSE.txt and NOTICE, which also lists the licenses of the dependencies built into the executable. Releases 0.1.0 and 0.1.1 were published under the Unlicense.