Installation

Tuist is a command-line application that you need to install in your environment before you can use it. The installation consists of an executable, dynamic frameworks, and a set of resources (for example, templates). Although you could manually build Tuist from the sources, we recommend using one of the following installation methods to ensure a valid installation.

Recommended: Mise

Tuist defaults to Mise as a tool to deterministically manage and activate versions of Tuist. If you don't have it installed on your system, you can use any of these installation methods. Remember to add the suggested line to your shell, which will ensure the right version is activated when you choose a Tuist project directory in your terminal session.

INFO

Mise is recommended over alternatives like Homebrew because it supports scoping and activating versions to directories, ensuring every environment uses the same version of Tuist deterministically.

Once installed, you can install Tuist through any of the following commands:

mise install tuist            # Install the current version specified in .tool-versions/.mise.toml
mise install [email protected]      # Install a specific version number
mise install tuist@3          # Install a fuzzy version number

Note that unlike tools like Homebrew, which install and activate a single version of the tool globally, Mise requires the activation of a version either globally or scoped to a project. This is done by running mise use:

mise use [email protected]          # Use tuist-x.y.z in the current project
mise use tuist@latest         # Use the latest tuist in the current directory
mise use -g [email protected]       # Use tuist-x.y.z as the global default
mise use -g tuist@system      # Use the system's tuist as the global default

Continuous integration

If you are using Tuist in a continuous integration environment, the following sections show how to install Tuist in the most common ones:

Xcode Cloud

You'll need a post-clone script that installs Mise and Tuist:

#!/bin/sh
curl https://mise.jdx.dev/install.sh | sh
mise install # Installs the version from .mise.toml

# Runs the version of Tuist indicated in the .mise.toml file
mise x tuist generate

Codemagic

To install and use Mise and Tuist in Codemagic, you can add an additional step to your workflow, and run Tuist through mise x tuist to ensure that the right version is used:

workflows:
  lint:
    name: Build
    max_build_duration: 30
    environment:
      xcode: 15.0.1
    scripts:
      - name: Install Mise
        script: |
          curl https://mise.jdx.dev/install.sh | sh
          mise install # Installs the version from .mise.toml
      - name: Build
        script: mise x tuist build

GitHub Actions

On GitHub Actions you can use the mise-action, which abstracts the installation of Mise and Tuist and the configuration of the environment:

name: test
on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main
jobs:
  lint:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      - uses: jdx/mise-action@v2

TIP

We recommend using mise use --pin in your Tuist projects to pin the version of Tuist across environments. The command will create a .tool-versions file containing the version of Tuist.

Alternative: Homebrew

If version pinning across environments is not a concern for you, you can install Tuist using Homebrew and our formulas:

brew tap tuist/tuist
brew install tuist
brew install [email protected]

Shell completions

If you have Tuist globally installed, you can install shell completions for Bash and Zsh to autocomplete commands and options.

What is a global installation

A global installation is an installation that's available in your shell's $PATH environment variable. This means you can run tuist from any directory in your terminal. This is the default installation method for Homebrew.

Zsh

If you have oh-my-zsh installed, you already have a directory of automatically loading completion scripts — .oh-my-zsh/completions. Copy your new completion script to a new file in that directory called _tuist:

tuist --generate-completion-script > ~/.oh-my-zsh/completions/_tuist

Without oh-my-zsh, you'll need to add a path for completion scripts to your function path, and turn on completion script autoloading. First, add these lines to ~/.zshrc:

fpath=(~/.zsh/completion $fpath)
autoload -U compinit
compinit

Next, create a directory at ~/.zsh/completion and copy the completion script to the new directory, again into a file called _tuist.

tuist --generate-completion-script > ~/.zsh/completion/_tuist

Bash

If you have bash-completion installed, you can just copy your new completion script to file /usr/local/etc/bash_completion.d/_tuist:

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

Without bash-completion, you'll need to source the completion script directly. Copy it to a directory such as ~/.bash_completions/, and then add the following line to ~/.bash_profile or ~/.bashrc:

source ~/.bash_completions/example.bash

Next steps

Once the installation is complete, you can start using Tuist to manage your projects. Here are some paths you might want to explore:

• Create a new project: If you are new to Tuist and don't have a project to migrate, you can start by creating a new project. We recommend introducing Tuist as early as possible in your project's lifecycle to be prepared for future growth and avoid laborious migrations.
• Use it with an existing Swift Package: If you have a project already declared using the Swift Package Manager, you might consider this option to explore how Tuist optimizations such as binary caching or selective testing might impact your workflows.