# Swift on Linux: Setup, Usage, and Platform Considerations

## Pro Summary

Swift for Linux ships as toolchains built per distribution release. swift.org now recommends the `swiftly` installer, which manages system dependencies and side-by-side versions, or the official `swift` Docker images instead of hand-extracted tarballs. Foundation on Linux is swift-corelibs-foundation layered on swift-foundation: `URLSession` lives in `FoundationNetworking`, XML APIs in `FoundationXML`, and you can import `FoundationEssentials` on its own to avoid the ICU payload. For portable binaries, either link the Swift runtime statically against glibc (`--static-swift-stdlib`) or cross-compile fully static musl binaries with the Static Linux SDK.

```
curl -O https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz && \
  tar zxf swiftly-$(uname -m).tar.gz && \
  ./swiftly init --quiet-shell-followup && \
  . "${SWIFTLY_HOME_DIR:-$HOME/.local/share/swiftly}/env.sh" && hash -r
swiftly install --use 6.4
swift build -c release --static-swift-stdlib
swift build --swift-sdk x86_64-swift-linux-musl   # Static Linux SDK
```

Requires: swift-docker publishes Swift 6.4 images for Ubuntu 22.04/24.04/26.04, Debian, Fedora, Amazon Linux and RHEL UBI. The Static Linux SDK must exactly match the installed swift.org toolchain version.

Gotchas:

- Dependency package names change between distro releases: the official Ubuntu 22.04 list uses `libgcc-11-dev`/`libstdc++-11-dev` plus `python3-lldb-13`, 24.04 uses the `-13-` variants, and the `-9-` names belong to Ubuntu 20.04, so copy the list from the matching swift-docker Dockerfile.
- Code that uses `URLSession` compiles on macOS and then fails on Linux with "cannot find 'URLSession' in scope" unless it adds `#if canImport(FoundationNetworking)` / `import FoundationNetworking` / `#endif`.
- The Static Linux SDK cannot be used with Xcode's toolchain on macOS and must match the swift.org toolchain version exactly, so after upgrading run `swift sdk list` and `swift sdk remove` on the old bundle before installing the new one.
- Linux has no Objective-C runtime, so code that relies on `@objc`, `#selector`, `NSObject` KVO or `dynamic` must stay behind `#if canImport(ObjectiveC)`.
- Debug builds are significantly slower than release builds, so build production binaries with `swift build -c release` and find them with `swift build --show-bin-path -c release` instead of hard-coding `.build/` paths.

Primary sources:

- [Install Swift on Linux (swift.org)](https://www.swift.org/install/linux/)
- [Getting Started with the Static Linux SDK (swift.org)](https://www.swift.org/documentation/articles/static-linux-getting-started.html)
- [swift-corelibs-foundation (Foundation modules on non-Darwin platforms)](https://github.com/swiftlang/swift-corelibs-foundation)
- [Building Swift server applications (swift.org)](https://www.swift.org/documentation/server/guides/building.html)

Source: https://devdocs10.com/articles/swift/swift-swift-on-linux  
By Murat Bo · Updated 2026-10-17 · DevDocs10 (https://devdocs10.com)

Swift runs well on Linux and is a practical choice for command-line tools, server-side applications, and package-based development. In this guide, you will learn what you need before installing Swift on Linux, how to install and verify it, how to configure your environment, and how to solve common setup problems that new Linux users often hit.

## 1. What You Need (Requirements)

Before installing Swift on Linux, make sure your system matches the requirements of the Swift toolchain you plan to use. Swift on Linux is distributed as prebuilt toolchains for selected distributions and versions, so compatibility matters more here than on some package-managed tools.

- A supported Linux distribution such as Ubuntu, Debian, or another distribution explicitly supported by the Swift release you want to use.
- A 64-bit Linux system. Most official Swift Linux toolchains target `x86_64` or `aarch64`.
- Basic terminal access and permission to install system packages.
- Development dependencies required by the Swift toolchain, such as C runtime and ICU-related libraries, depending on your distribution.
- Enough disk space for the toolchain, package caches, and compiled build artifacts.

> Swift on Linux is strongest for command-line and server-side development. Apple platform frameworks such as UIKit, AppKit, and SwiftUI are not available for native Linux app development.

You should also decide how you want to manage Swift versions. Some developers install one system-wide toolchain manually, while others keep multiple versions in separate directories and switch between them as needed.

## 2. Installation Steps

The exact installation steps depend on your Linux distribution. In general, you first install required system libraries, then download a Swift toolchain archive, extract it, and add Swift to your shell `PATH`.

> swift.org now recommends installing Swift on Linux with swiftly, its official toolchain installer. swiftly manages the toolchain and its dependencies and lets you switch between Swift versions:

```bash
curl -O https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz && \
  tar zxf swiftly-$(uname -m).tar.gz && \
  ./swiftly init --quiet-shell-followup && \
  . "${SWIFTLY_HOME_DIR:-$HOME/.local/share/swiftly}/env.sh" && \
  hash -r
```

The manual steps below are still useful for containers, air-gapped machines, and understanding what a toolchain installation contains.

### Ubuntu or Debian-based systems

First, update package indexes and install the dependencies that official Swift toolchains need on Ubuntu 22.04. This is the same list the official swift-docker image for Ubuntu 22.04 uses.

```bash
sudo apt-get update
sudo apt-get install -y \
  binutils \
  git \
  gnupg2 \
  libc6-dev \
  libcurl4-openssl-dev \
  libedit2 \
  libgcc-11-dev \
  libpython3-dev \
  libsqlite3-0 \
  libstdc++-11-dev \
  libxml2-dev \
  libz3-dev \
  pkg-config \
  python3-lldb-13 \
  tzdata \
  unzip \
  zlib1g-dev
```

This installs common runtime and development libraries used by Swift and Swift Package Manager. Package names vary slightly by distribution and release, so always compare them with the dependency list for your exact Swift version.

Next, download the toolchain archive from the official Swift download page and extract it. The exact file name changes by release.

```bash
wget https://download.swift.org/swift-5.9-release/ubuntu2204/swift-5.9-RELEASE/swift-5.9-RELEASE-ubuntu22.04.tar.gz
tar -xzf swift-5.9-RELEASE-ubuntu22.04.tar.gz
```

After extraction, move the directory to a stable location so shell configuration does not depend on your current working directory.

```bash
sudo mv swift-5.9-RELEASE-ubuntu22.04 /opt/swift-5.9
```

Then add Swift binaries to your shell `PATH`.

```bash
echo 'export PATH=/opt/swift-5.9/usr/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

At this point, the shell should be able to find commands such as `swift` and `swiftc`.

### Fedora or other RPM-based systems

On RPM-based systems, install the equivalent libraries using the native package manager before unpacking the Swift toolchain.

```bash
sudo dnf install -y \
  binutils \
  git \
  gcc-c++ \
  libcurl-devel \
  libedit \
  libxml2-devel \
  sqlite \
  python3-devel \
  zlib-devel
```

After that, the extraction and `PATH` setup steps are similar: download the correct archive, extract it, place it in a permanent directory, and export the binary path in your shell profile.

### Installing with a version manager or container

Some teams prefer not to install Swift manually into `/opt`. Instead, they use containers or automation scripts to keep developer environments consistent. This is especially useful in CI or when multiple Swift versions must coexist.

```bash
# Example: temporary shell PATH for one session
export PATH=/opt/swift-5.9/usr/bin:$PATH
swift --version
```

This temporary approach is useful for testing a new toolchain before making the change permanent.

## 3. Verifying the Installation

After installation, verify that the main Swift commands work and that the compiler can build a real program. Do not stop after checking only the version string.

### Verification Checklist

1. Check that the shell can find the Swift executable.
2. Check the installed Swift version.
3. Create and run a small Swift file.
4. Create a Swift Package Manager project and build it.

Run these commands first:

```bash
which swift
swift --version
which swiftc
```

Expected results:

- `which swift` should print a path such as `/opt/swift-5.9/usr/bin/swift`.
- `swift --version` should print a Swift 5+ version and target information.
- `which swiftc` should also point into the same toolchain directory.

Next, compile and run a small test program.

```bash
echo 'print("Hello from Swift on Linux")' > hello.swift
swift hello.swift
swiftc hello.swift -o hello
./hello
```

If both the interpreter-style invocation and the compiled binary run correctly, your basic Swift environment is working.

Finally, verify Swift Package Manager support.

```bash
swift package init --type executable
swift build
swift run
```

This confirms that package resolution, compilation, and executable launching all work in a standard project layout.

## 4. Recommended Initial Configuration

Once Swift is installed, spend a few minutes on initial configuration. This reduces friction later and helps avoid shell or editor confusion.

### Set the PATH in the correct shell profile

Linux systems may use different shells and startup files. Add Swift to the profile your shell actually loads.

```bash
# Bash
echo 'export PATH=/opt/swift-5.9/usr/bin:$PATH' >> ~/.bashrc

# Zsh
echo 'export PATH=/opt/swift-5.9/usr/bin:$PATH' >> ~/.zshrc
```

If you edit the wrong file, a new terminal session may still not find Swift.

### Confirm your editor uses the same toolchain

Editors sometimes start with a different environment than your terminal. Verify that integrated terminals and language tools point to the same Swift binary path.

> If your editor supports the Language Server Protocol, check whether it expects `sourcekit-lsp` from the installed Swift toolchain.

### Create a working directory for Swift packages

Swift development on Linux is usually package-based. Keep projects in a dedicated folder so builds, caches, and repositories stay organized.

```bash
mkdir -p ~/Projects/Swift
cd ~/Projects/Swift
swift package init --type executable
```

This gives you a predictable place to experiment with package creation, builds, and dependency management.

### Know the common toolchain commands

You will use a small set of commands often:

- `swift --version` to confirm the active toolchain.
- `swift file.swift` to run a single source file quickly.
- `swiftc` to compile files directly.
- `swift build` and `swift run` for package-based projects.

## 5. Common Setup Issues and Fixes

Swift on Linux setup problems are often caused by mismatched distributions, missing shared libraries, or incorrect shell configuration. Below are several common issues and their exact fixes.

### Issue 1: `swift: command not found`

This means the shell cannot find the Swift executable.

**Cause:** The toolchain is installed, but its `usr/bin` directory is not in your `PATH`, or the shell profile was not reloaded.

**Fix:** Add the correct path and reload the shell configuration.

```bash
echo 'export PATH=/opt/swift-5.9/usr/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
swift --version
```

If this still fails, run `ls /opt/swift-5.9/usr/bin/swift` to confirm the file exists.

### Issue 2: Missing shared library errors

You may see errors mentioning libraries such as ICU, XML, curl, or C++ runtime files.

**Cause:** Required system dependencies are not installed, or the toolchain was built for a different distribution version.

**Fix:** Install the missing packages for your distribution and verify that you downloaded the archive for the correct OS release.

```bash
sudo apt-get install -y libxml2-dev libcurl4-openssl-dev zlib1g-dev
```

**Warning:** A toolchain built for one Ubuntu release may not work correctly on another. Match the archive to your Linux version whenever possible.

### Issue 3: Swift builds in the terminal but not in the editor

This is a common environment mismatch.

**Cause:** GUI-launched editors may not load the same shell startup files as your terminal, so the editor cannot find the Swift toolchain or `sourcekit-lsp`.

**Fix:** Configure the editor with the explicit Swift toolchain path or launch the editor from a shell session where `PATH` is already correct.

```bash
which swift
which sourcekit-lsp
```

Use the printed paths in your editor settings if it supports manual configuration.

### Issue 4: Package builds fail because of networking or dependency resolution

**Cause:** Git is missing, network access is restricted, or package cache state is stale.

**Fix:** Install Git, confirm repository access, and retry dependency resolution.

```bash
sudo apt-get install -y git
swift package resolve
```

If corporate proxies or restricted networks are involved, Git and package access may need additional configuration outside Swift itself.

## 6. Keeping Things Updated

Swift releases regularly, and Linux developers often need to update toolchains manually. It is best to install new versions side by side rather than replacing the old one immediately.

A safe upgrade process looks like this:

1. Download the new Swift toolchain for your exact Linux distribution.
2. Extract it into a new versioned directory such as `/opt/swift-5.10`.
3. Temporarily update `PATH` in one shell session and verify builds.
4. Only after successful testing, update your shell profile to point to the new version.

Example temporary test:

```bash
export PATH=/opt/swift-5.10/usr/bin:$PATH
swift --version
swift build
```

This approach lets you test new compilers without breaking existing projects.

If you need to switch versions often, keep each toolchain in its own directory and make the active one explicit through shell aliases or per-project environment setup.

## 7. Key Points

- Swift on Linux is well suited to command-line tools, package-based projects, and server-side development.
- You must match the Swift toolchain to a supported Linux distribution and version.
- Installing dependencies is just as important as extracting the Swift archive.
- Always verify both `swift` and `swiftc`, then test a real package build.
- Most setup failures come from incorrect `PATH` settings or missing shared libraries.
- Upgrade by installing new toolchains side by side instead of overwriting old ones immediately.

## 8. Next Steps

After Swift is working on Linux, the most useful next steps are practical and package-focused.

- Create a new executable package with `swift package init --type executable` and explore the default project structure.
- Learn the difference between running a single file with `swift` and building a package with `swift build`.
- Practice editing `Package.swift` to understand package metadata and dependencies.
- Set up editor support with syntax highlighting, code completion, and optional `sourcekit-lsp` integration.
- Try a small command-line project such as a file parser, task tracker, or JSON formatter to get comfortable with Linux-based Swift workflows.

## 9. Final Summary

Swift on Linux is a solid development environment when you use a supported distribution, install the required dependencies, and configure your shell carefully. The core setup process is straightforward: install prerequisite packages, download the correct toolchain, add it to your `PATH`, and verify the installation with both simple files and a real Swift package.

Once the toolchain is working, Linux becomes a practical platform for learning Swift, building command-line tools, and developing server-side applications. A good next step is to create a small package-based project and get comfortable with `swift build`, `swift run`, and the standard project structure used across Swift development.

## Where AI Coding Assistants Get This Wrong

- Often suggested: Hard-codes `import Glibc` or `#if os(Linux) import Glibc` for C standard library access.
  Instead: Use a `canImport` chain, with each `import` on its own line: `#if canImport(Darwin)` then `import Darwin`, `#elseif canImport(Glibc)` then `import Glibc`, `#elseif canImport(Musl)` then `import Musl`, `#elseif os(Windows)` then `import ucrt`, `#endif`. Or depend on Foundation alone. (The Static Linux SDK is built on musl rather than glibc, so the `Glibc` module is not available when you build with it.)
- Often suggested: Writes networking code with only `import Foundation` and assumes it builds on Linux because it builds on macOS.
  Instead: Conditionally import `FoundationNetworking` (and `FoundationXML` for `XMLParser`), and run the build in a `swift:<version>` container or on Linux CI. (On non-Darwin platforms swift-corelibs-foundation ships `URLSession` in the separate `FoundationNetworking` module.)
- Often suggested: Gives outdated install steps: download a Swift 5.x tarball, pair it with an apt dependency list from a different Ubuntu release, and edit `PATH` by hand, or use Xcode's toolchain with the Static Linux SDK.
  Instead: Install with swiftly (`swiftly install --use <version>`, `.swift-version` per project) or use the official `swift` Docker images. For static binaries, install the Static Linux SDK that matches your swift.org toolchain with `swift sdk install <url> --checksum <sha>`. (These are the install paths that swift.org currently documents, and its static SDK guide says Xcode's toolchain can't use that SDK.)