Installation and Toolchain

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

This page is written against Vapor 4.122.2 (the latest 4.x release, 2026-09-17) on Swift 6.4 (the 6.4.1 release is the latest on swift.org), with the Vapor Toolbox 20.0.2 and Swiftly 1.2.0, checked on 2026-10-17. Vapor 4.122.x declares swift-tools-version:6.0, so any Swift 6.0 or newer toolchain can build it; the official vapor/template itself asks for tools version 6.3, so use a 6.3 or newer toolchain if you want to generate projects from it unchanged. Vapor 5 is published only as betas (5.0.0-beta.4, 2026-10-13) and needs Swift 6.4; this section targets Vapor 4, and the Vapor 5 differences that matter are called out where they arise (the What’s New, Upgrading and Vapor 5 page collects them). The next steps are the Getting Started page, which creates the first project, and the Introduction & Architecture page.

Nothing on this page is application code: it is the setup that the rest of the section assumes. If you only need the language toolchain, the Swift: Getting Started and Swift: Build and Tooling pages cover Swiftly, Xcode and the VS Code extension in general terms; this page adds the Vapor-specific parts.

What you need

A Vapor project needs exactly one mandatory thing: a Swift toolchain. Everything else is optional convenience.

Piece Required? Purpose

Swift 6.x toolchain (swift, swiftc, SwiftPM)

Yes

Compiles Vapor and your app and resolves packages. Vapor 4.122 needs Swift 6.0 or newer.

Vapor Toolbox (vapor)

No

Only generates a project from the template (vapor new). You can copy the template by hand instead.

Xcode (macOS) or VS Code with the Swift extension

No

Editing, debugging and running tests with an IDE.

Docker

No

Reproducible Linux builds, running on a Mac exactly what you deploy, and the supported route on Windows.

A database, Redis, and so on

No

Needed only by pages that use Fluent, Queues or Redis (see Fluent Overview and Database Drivers, Queues & Background Jobs and Redis & Caching); each of those pages installs what it needs.

The Vapor 4 documentation’s install pages still say "Vapor 4 requires Swift 5.9 or greater", which is the old minimum and no longer enough: the package manifests of current 4.x releases use tools version 6.0. Treat the Swift 6 numbers on this page as authoritative.

flowchart TD A[Which machine?] --> B{OS} B -->|macOS| C[Install Xcode] B -->|Linux| D[Install Swiftly] B -->|Windows| E[WSL2 Ubuntu or Docker] E --> D C --> F[swift --version] D --> F F --> G[brew install vapor - optional] G --> H[vapor new bookshelf]

macOS

Install Xcode from the Mac App Store and open it once so that it finishes installing its components. The Swift toolchain ships inside Xcode, so there is nothing else to download. Confirm it:

$ swift --version
swift-driver version: 1.168.6 Apple Swift version 6.4 (swiftlang-6.4.0.34.1 clang-2100.3.34.1)
Target: arm64-apple-macosx27.0.0

The exact numbers depend on your Xcode. What matters is the "Apple Swift version" being 6.0 or newer. If you have several Xcodes installed, xcode-select -p shows which one the command line uses and sudo xcode-select -s /Applications/Xcode.app switches it.

Source: Vapor docs: Install on macOS

The Command Line Tools alone (xcode-select --install) also give you a working swift for building a server, but you lose the Xcode IDE and its debugger integration, so the page assumes the full Xcode.

Homebrew and the Toolbox

Homebrew installs the Vapor Toolbox. If you do not have Homebrew, install it from brew.sh first:

$ brew install vapor
$ vapor --help

Source: Vapor docs: Install on macOS

The Toolbox 20 line requires macOS 15.0 or later (and, on Linux, any distribution that Swift 6.2 supports). Your application itself may target an older macOS: the template sets platforms: [.macOS(.v13)] in its Package.swift.

Linux

Vapor supports the same Linux distributions as Swift itself. The swift.org platform support page lists, among others, Ubuntu 22.04, Debian 12, Fedora 41, Amazon Linux 2023 and the Red Hat Universal Base Image 9; check the current list before choosing a server image, because it moves with every Swift release. Other distributions may work if you compile Swift from source, but Vapor does not promise stability there.

Source: Vapor docs: Install on Linux

Swiftly

Swiftly is the official Swift toolchain manager for macOS and Linux and the route Vapor recommends. It installs toolchains under your home directory (no root needed for the toolchain itself) and switches between them.

$ 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 latest
$ swift --version

Source: swift.org: Install Swift on Linux and Vapor docs: Install on Linux

swiftly init checks the system packages that Swift needs on your distribution and prints the ones that are missing; install what it lists with your package manager before the first build, otherwise compiling or linking can fail with missing header or library errors.

The commands you use afterwards:

Command What it does

swiftly install latest

Installs the newest stable toolchain and makes it the active one.

swiftly list-available

Lists the toolchains that can be installed.

swiftly use <version>

Switches the active toolchain (changes which swift is found on PATH).

swiftly update

Updates installed toolchains to the latest available patch releases.

swiftly uninstall <version> / swiftly uninstall all

Removes toolchains.

swiftly self-update

Upgrades Swiftly itself.

swiftly install main-snapshot

Installs a development snapshot, for experiments only.

Source: swiftlang/swiftly

Swiftly also supports sharing a preferred toolchain through a .swift-version file at the project root, which is how a team and the CI pin the same compiler. Whether you pin it or not, record the Swift version in the project README and in the Dockerfile so that a build on a laptop and a build in CI use the same compiler.

Manual toolchains and distribution packages

If you cannot use Swiftly, download a toolchain archive for your distribution from swift.org, unpack it and put its usr/bin on PATH. Fedora also ships Swift in its own repositories:

$ sudo dnf install swift-lang

Source: Vapor docs: Install on Linux

On Fedora 35 the Vapor page notes that EPEL 8 is needed to obtain a Swift new enough for Vapor; that release is long out of support, so on any current Fedora the package is simply available. Amazon Linux 2023 has its own install page on swift.org, under "Alternate Install Options".

Docker images

The official images are published on Docker Hub as swift (nightly builds and previews live in the swiftlang/swift namespace). They are the quickest way to try a Linux build from any host:

$ docker pull swift:latest
$ docker run --rm -it -v "$PWD":/app -w /app -p 8080:8080 swift:latest bash
root@c0ffee:/app# swift build

Source: swift.org: Using the Swift Docker images

The Vapor template’s own Dockerfile pins a Swift release and a distribution in the tag, for example swift:6.3-noble (Swift 6.3 on Ubuntu 24.04), uses it as a build stage and copies the result into a runtime image. Pin the tag the same way for reproducible builds; the full multi-stage setup is covered by the Deployment with Docker page, and the platforms that run the image by Deployment Targets.

Source: vapor/template: Dockerfile

Checking the toolchain with a real package

Before installing anything else, confirm that SwiftPM can fetch Vapor and compile against it. This is also a handy smoke test for a new CI image. Create an empty directory with this Package.swift:

// swift-tools-version:6.0
import PackageDescription

let package = Package(
    name: "toolchain-check",
    platforms: [.macOS(.v13)],
    dependencies: [
        .package(url: "https://github.com/vapor/vapor.git", from: "4.122.2")
    ],
    targets: [
        .executableTarget(
            name: "Check",
            dependencies: [.product(name: "Vapor", package: "vapor")]
        )
    ]
)

and Sources/Check/main.swift:

import Vapor

#if swift(>=6.0)
let compiler = "Swift 6 or newer"
#else
let compiler = "older than Swift 6"
#endif

#if os(Linux)
let platform = "Linux"
#elseif os(macOS)
let platform = "macOS"
#else
let platform = "other"
#endif

print("Compiler: \(compiler); platform: \(platform)")
print("Vapor Application type available: \(String(describing: Application.self))")
$ swift run Check
Compiler: Swift 6 or newer; platform: macOS
Vapor Application type available: Application

Source: swift.org: Swift Package Manager and Vapor docs: Swift Package Manager

The first build downloads and compiles Vapor and SwiftNIO and takes several minutes; later builds are incremental. The tools version in the manifest, not the compiler you run, decides the language mode: swift-tools-version:6.0 or later compiles the package in the Swift 6 language mode, which enables strict concurrency checking. An older tools version would silently build in Swift 5 mode, so keep the manifest in sync with what you document.

The Vapor Toolbox 20

The Toolbox is a small command line program whose job today is to create projects from a template. Version 20 has a single subcommand, new, which is also the default, so vapor new Hello -n and vapor Hello -n are the same.

$ vapor --help
$ vapor new bookshelf
Option Meaning

-n

Answers "no" to every question (no Fluent, no Leaf), producing the bare template.

--output <path>

Creates the project in a specific folder.

--no-git

Skips initialising a Git repository.

--no-commit

Initialises Git but skips the first commit.

--template <git URL>

Uses a custom template repository instead of vapor/template.

--branch <name>

Selects a template branch (default main).

--manifest <path>

Reads a manifest YAML or JSON file that describes the template’s questions.

--help

Shows the options, including those of a custom template.

Source: vapor/toolbox

How the questions work and what the generated project contains is the subject of the Getting Started and Project Structure and Swift Package Manager pages; here it is enough to know that the Toolbox is not required to run, build or deploy a Vapor app.

Building the Toolbox from source

The Toolbox is distributed through Homebrew on macOS and Linux (brew install vapor), but you can build it yourself, which is useful on a distribution without Homebrew or when you want an unreleased fix:

$ git clone https://github.com/vapor/toolbox.git
$ cd toolbox
$ git checkout 20.0.2
$ make install
$ vapor --help

make install accepts two variables: DEST chooses the installed path (make install DEST=/usr/local/bin/vapor) and SUDO=false avoids sudo when the destination is writable by your user.

Source: vapor/toolbox, installation

Editors

Xcode

Open the project by opening the folder or its Package.swift in Xcode: Xcode understands Swift packages natively, so no project file has to be generated. Pick the App scheme and a "My Mac" destination, then run.

The one setting every Vapor developer must change is the working directory. Xcode runs executables from its DerivedData folder, not from the project root, so Vapor cannot find .env files or the Public directory, and the console prints a warning like No custom working directory set for this scheme, using /path/to/DerivedData/.... Fix it once per scheme:

  1. Open the scheme selector next to the run and stop buttons and choose Edit Scheme…​.

  2. Select the App action and open the Options tab.

  3. Tick Use custom working directory and enter the project root (run pwd in a terminal opened there to get it).

Source: Vapor docs: Xcode

The setting is stored per scheme on your machine, so check it again after a fresh clone. Arguments such as serve --hostname 0.0.0.0 or --env production go in the same scheme editor, under Arguments.

Visual Studio Code

Install Swift first, then the extension swiftlang.swift-vscode from the VS Code Marketplace. It starts SourceKit-LSP for completion, go to definition, find references, rename, diagnostics and quick fixes; for Swift versions before 6.1 you have to run swift build once so that the index exists. Debugging uses the LLDB DAP extension (llvm-vs-code-extensions.lldb-dap), and the Swift extension creates a launch configuration for every executable target, so the App target appears automatically; edit .vscode/launch.json to set arguments and the working directory (${workspaceFolder}), which solves the same working-directory problem that Xcode has.

Source: swift.org: Getting started with VS Code

Other editors and SourceKit-LSP

Any editor that speaks the Language Server Protocol works with sourcekit-lsp, which ships in the Swift toolchain (Neovim, Emacs, Zed, Helix and others). Point it at the folder that contains Package.swift. Build once from the command line first so the index store is populated, and rebuild after dependency changes.

Windows

Vapor’s installation documentation covers macOS and Linux only; there is no Windows install page and Windows is not a supported platform for Vapor 4. (Swift itself has a Windows toolchain, but that does not make the server framework and its dependencies supported there.) The practical options are:

  1. WSL2. Install a supported distribution such as Ubuntu 22.04 or newer under WSL2, then follow the Linux section inside it: install Swiftly, run swiftly install latest and work in the Linux file system (~/projects), not under /mnt/c, because file access across that boundary makes SwiftPM builds very slow. VS Code’s WSL extension lets the Windows editor edit and debug the Linux checkout, and localhost:8080 in the Windows browser reaches a server listening in WSL2.

  2. Docker Desktop. Build and run in a swift container as shown above, mounting your sources. This also gives you the exact environment you deploy to.

Source: Vapor docs: Install on Linux and swift.org: Platform support

Run the server with --hostname 0.0.0.0 inside a container, because the default 127.0.0.1 is unreachable through Docker’s port mapping.

Version notes

Version Note

Vapor 4.122.x

Needs Swift 6.0 or newer (swift-tools-version:6.0). The template needs 6.3.

Vapor Toolbox 20

Only vapor new; requires macOS 15 or newer, or a Linux distribution supported by Swift 6.2.

Vapor 5 (beta)

Needs Swift 6.4 and macOS or iOS 26.2 for Apple platforms. Install the new toolchain with Swiftly (or Xcode) before trying it, and expect different template output; see What’s New, Upgrading and Vapor 5.

Vapor 3 to 4

Vapor 3 projects used Swift 4 or 5 and the Toolbox’s vapor build, vapor run and vapor xcode; none of those commands exist now.

Where the books are outdated

The instructions in older Vapor books no longer work and should be skipped:

  • The Vapor APT repository and check.vapor.sh. Early Vapor guides added a package repository on Ubuntu and ran a compatibility script. Both are gone; install Swift with Swiftly or a Docker image.

  • vapor xcode, vapor build, vapor run, vapor cloud and vapor heroku. Toolbox 20 has only new. Build with swift build, run with swift run App, and open Package.swift directly in Xcode.

  • swift package generate-xcodeproj. Removed from SwiftPM long ago; Xcode opens packages natively.

  • Old requirements. Swift 4 or 5.x, Xcode 9 to 11 and Ubuntu 14.04 to 18.04 are all far below Vapor 4.122’s minimum.

  • Toolbox generations. Homebrew now installs the 20.x Toolbox; the Toolbox versions the books show generate Vapor 2 or 3 projects (or use flags that no longer exist) that will not build with a current toolchain.

  • The installation page of the Vapor 4 docs still quotes Swift 5.9 as the minimum, as noted above.

References