System Environment Variables

Purpose and Scope

System environment variables are process-level inputs that change how the turbo command behaves before, during, or after task execution. They are different from application environment variables such as MY_API_URL: system variables configure Turborepo itself, while task environment variables are part of the task hash and runtime environment. Use this page when you need to tune terminal output, local cache behavior, Remote Cache authentication, binary discovery, framework inference, or CI behavior without permanently changing turbo.json or every script in your workspace.

Sources: apps/docs/content/docs/reference/system-environment-variables.mdx, apps/docs/content/docs/crafting-your-repository/using-environment-variables.mdx

The most important precedence rule is that command-line flags win over system environment variables. If a machine has TURBO_CACHE or TURBO_CACHE_DIR set but a CI step passes the corresponding turbo run flag, Turborepo follows the flag for that invocation. This makes environment variables useful for shared CI defaults, hosted platform configuration, and local machine overrides, while still allowing a specific command to be explicit when a workflow needs a one-off behavior.

Sources: apps/docs/content/docs/reference/system-environment-variables.mdx

This reference also separates two classes of environment concerns. The first class controls Turborepo: variables such as TURBO_API, TURBO_TOKEN, and TURBO_TEAM point the CLI at a Remote Cache and authenticate with it. The second class controls task hashing and task runtime: those variables are declared with globalEnv and task env in turbo.json, and they determine when cached task outputs are safe to reuse. Mixing these concepts is a common source of confusion, so review both this page and the environment-variable guide when diagnosing cache misses or stale deployments.

Sources: apps/docs/content/docs/crafting-your-repository/using-environment-variables.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx

Relevant Source Files

• apps/docs/content/docs/reference/system-environment-variables.mdx — Primary reference page for environment variables that control Turborepo behavior, including Remote Cache, cache directories, cache eviction, logging color, package-manager checks, and flag precedence.
• apps/docs/content/docs/crafting-your-repository/using-environment-variables.mdx — Explains the separate task-level environment model: globalEnv, task env, strict and loose environment modes, framework inference, and .env handling.
• apps/docs/content/blog/free-vercel-remote-cache.mdx — Documents the Vercel Remote Cache flow, including TURBO_TOKEN and TURBO_TEAM for non-Vercel CI providers and local turbo login plus turbo link setup.
• apps/docs/content/blog/joining-vercel.mdx — Provides historical context for Turborepo’s Vercel-backed zero-config Remote Cache and the open-source CLI transition.
• apps/docs/content/docs/guides/ci-vendors/github-actions.mdx — Shows concrete GitHub Actions usage for TURBO_TOKEN, TURBO_TEAM, and TURBO_REMOTE_ONLY in workflow environment configuration.
• apps/docs/content/docs/guides/ci-vendors/vercel.mdx — Describes Vercel’s zero-config Turborepo integration and automatic use of Vercel Remote Cache for imported monorepos.

Compact Reference

Sources: apps/docs/content/docs/reference/system-environment-variables.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx, apps/docs/content/docs/guides/ci-vendors/github-actions.mdx

Treat this table as a behavior map, not a replacement for command flags. Variables are convenient when a setting should apply to every turbo command in a shell, container image, hosted platform, or CI job. Flags are better when the setting belongs to one task invocation. For example, a workflow can set TURBO_TOKEN and TURBO_TEAM at the job level so every pnpm build or pnpm test can use Remote Cache, but an individual debugging step can still pass cache flags directly to isolate reads, writes, or directories for that run.

Runtime Environment Versus Task Hashing

Application environment variables must be declared to Turborepo when they influence task outputs. The environment-variable guide frames this around three questions: whether variables are accounted for in the task hash, which Environment Mode turbo will use, and whether .env files have been handled. The hash-related answer lives in turbo.json: globalEnv affects all task hashes, while a task’s env list affects only that task. This lets a build task depend on an API URL without making an unrelated lint task miss cache when that value changes.

Sources: apps/docs/content/docs/crafting-your-repository/using-environment-variables.mdx

Framework Inference is the bridge between common frontend conventions and Turborepo’s explicit hashing model. For supported frameworks, Turborepo automatically adds known public environment-variable prefixes, such as NEXT_PUBLIC_* for Next.js and VITE_* for Vite, on a per-package basis. The TURBO_CI_VENDOR_ENV_KEY system variable belongs to this area because it tells Turborepo about CI vendor variables that should be excluded from inference. In normal use, the docs note that users should not need to set that variable themselves because supported platforms configure it automatically.

Sources: apps/docs/content/docs/reference/system-environment-variables.mdx, apps/docs/content/docs/crafting-your-repository/using-environment-variables.mdx

Environment Modes control which variables are available to the task process at runtime. Strict Mode is the default and filters runtime variables to those listed in env and globalEnv; Loose Mode allows a broader environment through. This matters because a task can accidentally succeed locally by reading a variable that was never declared for hashing, then restore or produce the wrong output in CI. When troubleshooting unexpected cache hits, first verify whether the variable is a system variable that configures Turborepo or an application variable that should be declared for task hashing.

Sources: apps/docs/content/docs/crafting-your-repository/using-environment-variables.mdx

Remote Cache and CI Workflows

Remote Cache variables are most visible in CI. The Vercel Remote Cache announcement states that commands using turbo on Vercel are automatically configured to use Vercel Remote Cache, so projects imported into Vercel benefit from zero-configuration caching. On other CI providers, you create TURBO_TOKEN and TURBO_TEAM environment variables with the appropriate values. Locally, the same flow is expressed as commands rather than preconfigured environment: npx turbo login followed by npx turbo link connects a repository to the cache.

Sources: apps/docs/content/blog/free-vercel-remote-cache.mdx, apps/docs/content/docs/guides/ci-vendors/vercel.mdx

The GitHub Actions guide shows the practical placement of these variables. In the workflow job, Remote Caching is enabled by adding an env block with TURBO_TOKEN sourced from repository secrets and TURBO_TEAM sourced from repository variables. The npm example also shows TURBO_REMOTE_ONLY: true, which is useful when a CI job should rely on the remote cache rather than preserving local filesystem cache state. Keep the secret value out of logs, and prefer job-level environment configuration when both build and test tasks should share the same cache identity.

Sources: apps/docs/content/docs/guides/ci-vendors/github-actions.mdx

jobs:
  build:
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
      TURBO_REMOTE_ONLY: true

The Vercel guide describes the opposite operational model: import the repository into Vercel, and the integration pre-configures the correct settings to use Vercel Remote Cache. That means teams deploying on Vercel usually do not start by hand-authoring TURBO_TOKEN and TURBO_TEAM for the Vercel build itself. They still may need those variables for other providers, scheduled jobs, or local automation that should share the same artifacts with Vercel deployments.

Sources: apps/docs/content/docs/guides/ci-vendors/vercel.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx

Cache Storage, Eviction, and Debugging Decisions

Local cache variables control where artifacts live and how long they remain useful. TURBO_CACHE_DIR changes the directory used for the local cache, which can be helpful in containers, ephemeral CI runners, or developer machines with custom disk layouts. TURBO_CACHE_MAX_AGE and TURBO_CACHE_MAX_SIZE bound the cache by time and disk usage. When the size limit is exceeded, the oldest local filesystem cache entries are evicted. These settings are machine policy, so environment variables are often more appropriate than repository configuration when teams have heterogeneous developer hardware.

Sources: apps/docs/content/docs/reference/system-environment-variables.mdx

TURBO_CACHE is broader than the directory setting because it controls reading and writing for cache sources using the same syntax as the --cache run option. Use it when an environment should consistently disable, restrict, or redirect cache reads and writes. In contrast, use a direct flag when investigating a single cache issue, because flags override variables and make the command self-documenting. This distinction is especially useful in CI debugging: change one command first, then promote the behavior to environment configuration only after you know it should be permanent.

Sources: apps/docs/content/docs/reference/system-environment-variables.mdx

TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK should be treated as a last-resort compatibility setting. The reference warns that disabling the root package.json package-manager declaration check can lead to errors and unexpected caching behavior. That warning matters because the package manager and lockfile are part of Turborepo’s understanding of the workspace. If developers and CI resolve dependencies differently, a task hash can no longer represent the same inputs across machines. Prefer declaring the package manager correctly, and use the disabling variable only while unblocking a controlled migration.

Sources: apps/docs/content/docs/reference/system-environment-variables.mdx

Practical Next Steps

When adding a new variable, decide which layer owns it. If it configures Turborepo itself, put it in the shell, CI job, deployment platform, or command invocation, and remember that a flag can override it. If it changes application output, declare it in globalEnv or task env so cache keys reflect the value. For Remote Cache on Vercel, rely on the platform integration first; for GitHub Actions or another provider, add TURBO_TOKEN and TURBO_TEAM to the CI environment and keep credentials in the provider’s secret store.

Sources: apps/docs/content/docs/reference/system-environment-variables.mdx, apps/docs/content/docs/crafting-your-repository/using-environment-variables.mdx, apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/docs/guides/ci-vendors/vercel.mdx

Next, read the turbo.json Configuration reference for globalEnv, env, cacheMaxAge, and cacheMaxSize; read turbo run for cache flags; and read the CI vendor guide that matches your deployment system. If a cache result seems wrong, compare the command flags, system variables, task environment declarations, and platform-provided Remote Cache settings in that order.