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)
Direct Download
Build from Source
Docker

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

brew install 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

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:

Go to Tuist Releases
Download the latest tuist.zip
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 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.

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

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

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
Zsh
Fish

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

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

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:

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:

Create .mise.toml in your project root:
```
[tools]
tuist = "4.0.0"
```
Commit this file to version control
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
Direct Download
From Source

Update to latest

mise use tuist@latest
mise install

Update to specific version

mise use tuist@4.1.0
mise install

Re-run installer

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

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
Direct Installation

Remove from project

mise uninstall tuist

Remove globally

mise uninstall -g tuist

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

Get Started

Core Concepts

Features

Guides

Documentation Index

​Installing Tuist

​System Requirements

macOS

Linux

Xcode (macOS only)

Swift

​Installation Methods

​Why Mise?

​Install Mise

​Use Tuist with Mise

​Specify a version

​Update Tuist

​Download and install

​Verify installation

​Manual installation

​Update

​Prerequisites

​Clone and build

​Install locally

​Development workflow

​Run tests

​Official Docker image

​Available tags

​Use in CI

​Verify Installation

​Shell Completion

​Authentication

Cloud Services

​Troubleshooting

​Update Tuist

​Uninstall Tuist

​Next Steps

Quickstart

CLI Reference

Core Concepts

Cloud Setup

​Additional Resources

Changelog

Contributing

GitHub

Build docs developers (and LLMs) love

Installing Tuist

System Requirements

Installation Methods

Why Mise?

Install Mise

Use Tuist with Mise

Specify a version

Update Tuist

Download and install

Verify installation

Manual installation

Update

Prerequisites

Clone and build

Install locally

Development workflow

Run tests

Official Docker image

Available tags

Use in CI

Verify Installation

Shell Completion

Authentication

Troubleshooting

Update Tuist

Uninstall Tuist

Next Steps

Additional Resources