Stop version drift and installation headaches — pin Tuist per project, fix 'command not found', and keep teammates and CI perfectly in sync with a version manager.
Tuist evolves, and manifests can depend on behavior specific to a version. When teammates or CI run different Tuist versions, you get failures that reproduce on one machine but not another.
Symptoms include generation that works locally but breaks in CI, cryptic manifest errors after someone upgrades, or the dreaded `tuist: command not found`.
These are environment problems, not code problems. The cure is making the Tuist version explicit, pinned, and identical everywhere.
This guide walks through diagnosing and permanently fixing version and installation drift.
If you see `command not found`, the shell cannot locate the `tuist` binary. First confirm it is installed at all by checking your installation method.
Ensure the install location is on your PATH. Depending on how you installed Tuist — an install script or a version manager — the binary lives in different places.
Open a fresh terminal after installing, since PATH changes may not apply to an existing session.
Once `tuist version` prints a number, the binary is found, and you can move on to consistency concerns.
Run `tuist version` and note the exact value. Then compare it against what your project expects and what CI uses.
Mismatches here are the root of most "works on my machine" reports. A manifest written against one version may rely on API or behavior that differs in another.
Ask teammates to run the same command and compare. If versions differ, you have found your culprit.
Record the intended version somewhere authoritative in the repo so there is a single source of truth to check against.
The durable fix is to pin Tuist per project using a version manager such as `mise`. This ensures everyone who works in the repo uses the exact same version automatically.
With a pinned version committed to the repo, cloning the project and running Tuist uses the specified version without anyone thinking about it.
This eliminates drift between developers and between local and CI environments, which is where most version pain originates.
Make pinning a first-class part of project setup rather than an afterthought, and document it in your README.
CI is a frequent offender because it may install whatever version is latest at run time, silently diverging from developer machines.
Configure CI to install and use the same pinned Tuist version your version manager specifies. If you pin with a tool CI also supports, this can be automatic.
Avoid steps that grab the newest Tuist unconditionally, since an upstream release can then break your pipeline overnight with no code change on your side.
After aligning, trigger a CI run and confirm it reports the expected version before it generates.
When you do want to upgrade Tuist, treat it as a deliberate change, not an accident. Bump the pinned version in one commit so the whole team and CI move together.
Read the release notes for the target version. Breaking changes to manifest APIs or expected file layouts are called out there and may require manifest edits.
Regenerate and build after upgrading, and fix any new diagnostics before merging the bump.
Coordinating upgrades this way prevents the classic situation where one person upgrades locally and breaks everyone else.
After switching versions, old caches or generated artifacts built by a different version can cause confusing behavior.
Delete the generated `.xcodeproj` and `.xcworkspace`, clear Tuist caches per the documentation for your version, and regenerate from scratch.
If you use external dependencies, run `tuist install` again so packages are resolved under the new version before generating.
A clean regeneration ensures the new version is truly in control and no leftover state is masking the change.
A subtle cause of version confusion is having Tuist installed more than one way at the same time, so the version you think you are running is not the one the shell actually picks.
If you once used an install script and later adopted a version manager, both binaries can linger, and PATH ordering decides which wins. That is a recipe for surprising mismatches.
Check which `tuist` your shell resolves and where it lives. If it is not the version-manager-controlled one, remove or supersede the stray installation so the pinned version is unambiguously in charge.
Settling on a single installation mechanism per machine removes an entire category of hard-to-explain version problems before they start.
The lasting fix is cultural and mechanical: pin the version, commit the pin, and make both local and CI honor it. Then version drift simply cannot happen silently.
Add a short note to your README explaining how to install the version manager and that Tuist is pinned, so new contributors are productive immediately.
Periodically and deliberately upgrade as a team, reading release notes and testing before merging.
And keep perspective: getting Tuist consistent fixes your project-generation layer. Building for release, signing, and submitting still depend on Xcode and a paid Apple Developer Program membership, which are unaffected by your Tuist version.
When a version or install problem strikes, this short checklist gets you to the cause quickly instead of guessing.
First, run `tuist version`. If it fails with `command not found`, the binary is not on your PATH or your shell predates the install — open a fresh terminal and confirm the install location.
Second, if it does print, compare that version against what the project expects and what CI uses. A mismatch here explains most 'works on my machine' reports.
Third, confirm you are not running two conflicting installations at once, since PATH ordering can silently pick the wrong one.
The durable resolution to all of these is the same: pin a single Tuist version with a version manager, commit the pin, make CI honor it, and clear stale generated files after any version change. Do that once and this whole category of failures stops recurring across your team.
Treat this as a one-time investment with a lasting payoff. The half hour spent pinning a version, aligning CI, and documenting the setup in your README saves far more than that across a team, because it removes the recurring, hard-to-reproduce failures that version drift quietly produces month after month.
Almost always a version mismatch. CI may install a different Tuist version than your machine. Pin the version and configure CI to use the same one.
Use a version manager such as mise to specify and commit the exact Tuist version in the repo. Everyone who works in the project then uses that version automatically.
The binary isn't on your PATH, or your current shell predates the install. Open a fresh terminal, confirm the install location is on PATH, and check tuist version.
Bump the pinned version in a single commit so the team and CI move together, read the release notes for breaking changes, then regenerate and build before merging.