1# Global Options Reference
2 
3Options that affect all tasks. Full docs: https://turborepo.dev/docs/reference/configuration
4 
5## globalEnv
6 
7Environment variables affecting all task hashes.
8 
9```json
10{
11  "globalEnv": ["CI", "NODE_ENV", "VERCEL_*"]
12}
13```
14 
15Use for variables that should invalidate all caches when changed.
16 
17## globalDependencies
18 
19Files that affect all task hashes.
20 
21```json
22{
23  "globalDependencies": ["tsconfig.json", ".env", "pnpm-lock.yaml"]
24}
25```
26 
27Lockfile is included by default. Add shared configs here.
28 
29## globalPassThroughEnv
30 
31Variables available to tasks but not included in hash.
32 
33```json
34{
35  "globalPassThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
36}
37```
38 
39Use for credentials that shouldn't affect cache keys.
40 
41## cacheDir
42 
43Custom cache location. Default: `node_modules/.cache/turbo`.
44 
45```json
46{
47  "cacheDir": ".turbo/cache"
48}
49```
50 
51## daemon
52 
53**Deprecated**: The daemon is no longer used for `turbo run` and this option will be removed in version 3.0. The daemon is still used by `turbo watch` and the Turborepo LSP.
54 
55## envMode
56 
57How unspecified env vars are handled. Default: `"strict"`.
58 
59```json
60{
61  "envMode": "strict"  // Only specified vars available
62  // or
63  "envMode": "loose"   // All vars pass through
64}
65```
66 
67Strict mode catches missing env declarations.
68 
69## ui
70 
71Terminal UI mode. Default: `"stream"`.
72 
73```json
74{
75  "ui": "tui"     // Interactive terminal UI
76  // or
77  "ui": "stream"  // Traditional streaming logs
78}
79```
80 
81TUI provides better UX for parallel tasks.
82 
83## remoteCache
84 
85Configure remote caching.
86 
87```json
88{
89  "remoteCache": {
90    "enabled": true,
91    "signature": true,
92    "timeout": 30,
93    "uploadTimeout": 60
94  }
95}
96```
97 
98| Option          | Default                | Description                                            |
99| --------------- | ---------------------- | ------------------------------------------------------ |
100| `enabled`       | `true`                 | Enable/disable remote caching                          |
101| `signature`     | `false`                | Sign artifacts with `TURBO_REMOTE_CACHE_SIGNATURE_KEY` |
102| `preflight`     | `false`                | Send OPTIONS request before cache requests             |
103| `timeout`       | `30`                   | Timeout in seconds for cache operations                |
104| `uploadTimeout` | `60`                   | Timeout in seconds for uploads                         |
105| `apiUrl`        | `"https://vercel.com"` | Remote cache API endpoint                              |
106| `loginUrl`      | `"https://vercel.com"` | Login endpoint                                         |
107| `teamId`        | -                      | Team ID (must start with `team_`)                      |
108| `teamSlug`      | -                      | Team slug for querystring                              |
109 
110See https://turborepo.dev/docs/core-concepts/remote-caching for setup.
111 
112## concurrency
113 
114Default: `"10"`
115 
116Limit parallel task execution.
117 
118```json
119{
120  "concurrency": "4"     // Max 4 tasks at once
121  // or
122  "concurrency": "50%"   // 50% of available CPUs
123}
124```
125 
126## futureFlags
127 
128Enable experimental features that will become default in future versions.
129 
130```json
131{
132  "futureFlags": {
133    "errorsOnlyShowHash": true
134  }
135}
136```
137 
138### `errorsOnlyShowHash`
139 
140When using `outputLogs: "errors-only"`, show task hashes on start/completion:
141 
142- Cache miss: `cache miss, executing <hash> (only logging errors)`
143- Cache hit: `cache hit, replaying logs (no errors) <hash>`
144 
145### `longerSignatureKey`
146 
147Enforce a minimum key length of 32 bytes for `TURBO_REMOTE_CACHE_SIGNATURE_KEY` when `remoteCache.signature` is enabled. Short keys weaken HMAC-SHA256 signatures. Fails the run immediately if the key is too short.
148 
149### `globalConfiguration`
150 
151Moves global configuration keys under a top-level `global` key for clarity and changes how `global.inputs` (formerly `globalDependencies`) affects task hashing.
152 
153When enabled:
154 
155- Global config keys move under `global` with cleaner names
156- `global.inputs` files are **prepended to every task's inputs** instead of being folded into the global hash — tasks can opt out of specific global inputs using negation globs
157 
158```json
159{
160  "futureFlags": { "globalConfiguration": true },
161  "global": {
162    "inputs": ["tsconfig.json", ".env"],
163    "env": ["CI", "NODE_ENV"],
164    "passThroughEnv": ["AWS_SECRET_KEY"],
165    "ui": "tui",
166    "envMode": "strict",
167    "cacheDir": ".turbo/cache",
168    "remoteCache": { "enabled": true },
169    "concurrency": "50%"
170  },
171  "tasks": {
172    "build": {
173      "dependsOn": ["^build"],
174      "outputs": ["dist/**"]
175    }
176  }
177}
178```
179 
180**Key rename mapping:**
181 
182| Old (top-level)                                                                                                                  | New (`global.`)           |
183| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
184| `globalDependencies`                                                                                                             | `inputs`                  |
185| `globalEnv`                                                                                                                      | `env`                     |
186| `globalPassThroughEnv`                                                                                                           | `passThroughEnv`          |
187| `ui`, `envMode`, `cacheDir`, `daemon`, `concurrency`, `noUpdateNotifier`, `dangerouslyDisablePackageManagerCheck`, `remoteCache` | Same names under `global` |
188 
189**Behavior change for `global.inputs`:**
190 
191With `globalDependencies` (old): files are hashed into the **global hash**, which is embedded in every task's cache key. Changing any of these files invalidates all tasks — there is no opt-out.
192 
193With `global.inputs` (new): files are treated as **implicit task inputs** prepended to each task's `inputs` globs. This means:
194 
195- Tasks can exclude specific global files: `"inputs": ["$TURBO_DEFAULT$", "!$TURBO_ROOT$/tsconfig.json"]`
196- The global hash no longer includes these file hashes (it still includes lockfile, engines, global env, etc.)
197- Tasks with no explicit `inputs` still hash all package files plus the global inputs
198 
199See the [gotchas doc](./gotchas.md) for guidance on using `$TURBO_DEFAULT$` with `global.inputs`.
200 
201## noUpdateNotifier
202 
203Disable update notifications when new turbo versions are available.
204 
205```json
206{
207  "noUpdateNotifier": true
208}
209```
210 
211## dangerouslyDisablePackageManagerCheck
212 
213Bypass the `packageManager` field requirement. Use for incremental migration.
214 
215```json
216{
217  "dangerouslyDisablePackageManagerCheck": true
218}
219```
220 
221**Warning**: Unstable lockfiles can cause unpredictable behavior.
222 
223## Git Worktree Cache Sharing
224 
225When working in Git worktrees, Turborepo automatically shares local cache between the main worktree and linked worktrees.
226 
227**How it works:**
228 
229- Detects worktree configuration
230- Redirects cache to main worktree's `.turbo/cache`
231- Works alongside Remote Cache
232 
233**Benefits:**
234 
235- Cache hits across branches
236- Reduced disk usage
237- Faster branch switching
238 
239**Disabled by**: Setting explicit `cacheDir` in turbo.json.
240