From 70deaaee3fb4bfb1347264908a2f034f20047c4c Mon Sep 17 00:00:00 2001
From: Anthony Shew <anthony.shew@vercel.com>
Date: Tue, 30 May 2023 06:08:27 -0700
Subject: [PATCH] feat(docs): multiple global turbo FAQ. (#5119)

---
 docs/pages/repo/docs/faq.mdx        | 30 +++++++++++++++++++++++++++++
 docs/pages/repo/docs/installing.mdx |  2 ++
 2 files changed, 32 insertions(+)

diff --git a/docs/pages/repo/docs/faq.mdx b/docs/pages/repo/docs/faq.mdx
index 6b441701cdc07..b830bfe22a114 100644
--- a/docs/pages/repo/docs/faq.mdx
+++ b/docs/pages/repo/docs/faq.mdx
@@ -4,6 +4,7 @@ description: Frequently asked questions about Turborepo.
 ---
 
 import Callout from '../../../components/Callout'
+import { Tabs, Tab } from '../../../components/Tabs'
 
 # Frequently Asked Questions
 
@@ -16,6 +17,35 @@ You have two options when working with Turborepo:
 
 We recommend installing the `turbo` CLI globally. This gives you a smooth, ergonomic experience for running tasks.
 
+### Why isn't my global `turbo` working as expected?
+
+It's possible to end up with multiple versions of global `turbo` on your machine if you install with different package managers. This can cause unexpected behavior if you're accidentally executing an older version of `turbo`.
+
+You can quickly check which package manager's version you are using with:
+
+- macOS and Linux: `which turbo`
+- Windows: `where turbo`
+
+The easiest way to ensure stability is to run the uninstall commands for your non-preferred package managers:
+
+  <Tabs items={['npm', 'yarn', 'pnpm']} storageKey="selected-pkg-manager">
+    <Tab>
+      ```bash
+      npm uninstall turbo --global
+      ```
+    </Tab>
+    <Tab>
+      ```bash
+      yarn global remove turbo
+      ```
+    </Tab>
+    <Tab>
+      ```bash
+      pnpm uninstall turbo --global
+      ```
+    </Tab>
+  </Tabs>
+
 ## Do I have to use Remote Caching to use Turborepo?
 
 No. [Remote Caching](/repo/docs/core-concepts/remote-caching) is optional. However, you'll find it very useful to speed up development on a team, speed up builds inside of Docker, and also save space on your own machine.
diff --git a/docs/pages/repo/docs/installing.mdx b/docs/pages/repo/docs/installing.mdx
index 75c5580e0d4be..41b904dbbfae4 100644
--- a/docs/pages/repo/docs/installing.mdx
+++ b/docs/pages/repo/docs/installing.mdx
@@ -52,6 +52,8 @@ cd <repository root>
 turbo build --filter=docs
 ```
 
+If you've installed global `turbo` before, make sure you use the same package manager as your existing installation to avoid unexpected behaviors. For more info, [visit the FAQ](/repo/docs/faq#should-i-install-turborepo-globally).
+
 ## Install Per Repository
 
 You may wish to pin the version of Turborepo used within a repository, especially [if you are