Installation

Install Tuist on your machine using various methods

Installing Tuist

Tuist is a command-line tool written in Swift that runs on macOS and Linux. This guide covers all available installation methods.

System Requirements

macOS

macOS 12.0 or later for full functionality (including Xcode project generation)

Linux

Ubuntu 20.04+ or other modern Linux distributions for server commands

Xcode (macOS only)

Xcode 14.0 or later with Command Line Tools installed

Swift

Swift 5.9 or later (included with Xcode on macOS)

On Linux, commands requiring Xcode (like tuist generate or tuist build) won’t work. However, commands for authentication, project management, analytics, and scaffolding work perfectly.

Installation Methods

Choose the installation method that best fits your workflow:

Mise (Recommended)

Mise is a versatile development tool version manager that handles Tuist installation and versioning.

Why Mise?

• Version pinning: Ensures all team members use the same Tuist version
• Project isolation: Different projects can use different Tuist versions
• Automatic activation: Switches to the correct version when entering a project directory
• Zero configuration: Works out of the box with .mise.toml files

Install Mise

macOS (Homebrew)

brew install mise

curl https://mise.run | sh

apt update -y && apt install -y gpg sudo wget curl
sudo install -dm 755 /etc/apt/keyrings
wget -qO - https://mise.jdx.dev/gpg-key.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg 1> /dev/null
echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=amd64] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list
sudo apt update
sudo apt install -y mise

Use Tuist with Mise

Option 1: Run without installation

mise x tuist@latest -- tuist init

Option 2: Install in your project

cd your-project
mise use tuist@latest

This creates a .mise.toml file:

.mise.toml

[tools]
tuist = "latest"

Option 3: Install globally

mise use -g tuist@latest

Specify a version

Pin specific version

mise use tuist@4.0.0

Pin to major version

mise use tuist@4

Commit .mise.toml to version control so your team uses consistent Tuist versions.

Update Tuist

Update to latest

mise use tuist@latest

Update and regenerate lockfile

mise install

Direct Download

Download the Tuist binary directly from GitHub releases.

Download and install

Download latest release

curl -Ls https://install.tuist.io | bash

This script:

• Downloads the latest Tuist release
• Installs it to /usr/local/bin/tuist
• Makes it available globally

Verify installation

tuist --version

Manual installation

If you prefer manual installation:

1. Go to Tuist Releases
2. Download the latest tuist.zip
3. Extract and move to your PATH:

unzip tuist.zip
mv tuist /usr/local/bin/
chmod +x /usr/local/bin/tuist

Update

Re-run the installation command to update to the latest version:

curl -Ls https://install.tuist.io | bash

Direct installation doesn’t provide version management. For version pinning, use Mise instead.

Build from Source

Build Tuist from source for development or to use unreleased features.

Prerequisites

• Xcode 14.0 or later (macOS)
• Swift 5.9 or later (Linux)
• Git

Clone and build

Clone repository

git clone https://github.com/tuist/tuist.git
cd tuist

Build for macOS

mise run cli:build:release

Build for Linux

swift build -c release

Install locally

cp .build/release/tuist /usr/local/bin/

Development workflow

For development, use the generated Xcode project:

mise run cli:generate

This opens Tuist.xcworkspace where you can develop and debug.

Run tests

Run all tests

mise run cli:test

Run specific tests

mise run cli:test --filter MyTests

Building from source is primarily for contributors. For regular use, prefer Mise or direct download.

Docker

Use Tuist in Docker containers for CI/CD or isolated environments.

Official Docker image

Tuist provides official Docker images on GitHub Container Registry.

Dockerfile

FROM ghcr.io/tuist/tuist:latest

WORKDIR /app
COPY . .

RUN tuist generate

Available tags

• latest: Latest stable release
• 4: Latest 4.x version
• 4.0.0: Specific version

Use in CI

GitHub Actions

name: Build
on: [push]

jobs:
  build:
    runs-on: macos-latest
    container:
      image: ghcr.io/tuist/tuist:latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate project
        run: tuist generate
      - name: Build
        run: tuist build

image: ghcr.io/tuist/tuist:latest

build:
  script:
    - tuist generate
    - tuist build

Docker images for Tuist are Linux-based. Xcode-specific commands won’t work. Use macOS runners with Mise for full functionality.

Verify Installation

After installation, verify Tuist is working correctly:

Check version

tuist --version

Check help

tuist --help

You should see output showing the Tuist version and available commands.

Shell Completion

Enable shell completion for a better command-line experience:

Bash

tuist --generate-completion-script bash > /usr/local/etc/bash_completion.d/tuist

Zsh

tuist --generate-completion-script zsh > /usr/local/share/zsh/site-functions/_tuist

Fish

tuist --generate-completion-script fish > ~/.config/fish/completions/tuist.fish

Restart your shell for completions to take effect.

Authentication

Many Tuist features require authentication with Tuist Cloud:

Login to Tuist Cloud

tuist auth login

This opens your browser to authenticate. Once logged in, you can:

• Use the cache
• Share app previews
• Access build insights
• Manage projects and organizations

Check authentication status

tuist auth whoami

Cloud Services

Learn more about Tuist Cloud features and pricing

Troubleshooting

Command not found: tuist

The tuist binary isn’t in your PATH. Solutions:

Using Mise:

mise doctor
mise reshim

Direct installation:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Permission denied

The binary doesn’t have execute permissions:

chmod +x /usr/local/bin/tuist

Version mismatch in team

Different team members are using different Tuist versions.

Solution: Use Mise with version pinning:

1. Create .mise.toml in your project root:

   [tools]
   tuist = "4.0.0"
   

2. Commit this file to version control

3. Team members run:

   mise install
   

macOS Gatekeeper warning

macOS may block the binary because it’s downloaded from the internet.

xattr -d com.apple.quarantine /usr/local/bin/tuist

Or allow it in System Preferences → Security & Privacy.

Xcode Command Line Tools missing

Some features require Xcode Command Line Tools:

xcode-select --install

Update Tuist

Keep Tuist up to date for the latest features and fixes:

Mise

Update to latest

mise use tuist@latest
mise install

Update to specific version

mise use tuist@4.1.0
mise install

Direct Download

Re-run installer

curl -Ls https://install.tuist.io | bash

From Source

cd tuist
git pull
mise run cli:build:release
cp .build/release/tuist /usr/local/bin/

Uninstall Tuist

If you need to uninstall Tuist:

Mise

Remove from project

mise uninstall tuist

Remove globally

mise uninstall -g tuist

Direct Installation

rm /usr/local/bin/tuist

Next Steps

Now that Tuist is installed:

Quickstart

Create your first project with Tuist

CLI Reference

Explore available commands

Core Concepts

Learn about Tuist’s architecture

Cloud Setup

Set up authentication for cloud features

Additional Resources

Changelog

See what’s new in each release

Contributing

Contribute to Tuist development

GitHub

Star us on GitHub