Environment Variables¶

FastVideo reads environment variables for expert switches, debugging, profiling, and the settings that launchers such as torchrun provide. This page is the policy for those variables. The contract test fastvideo/tests/contract/test_env_policy.py enforces the policy in the unit CI lane, and the coding-agent skill .agents/skills/env-var-conventions/SKILL.md points here. When the policy changes, update this page and the contract test in the same pull request.

Rules¶

1. Register every FastVideo variable in fastvideo/envs.py. Each entry declares a type, a default, a category, and a description. Variables that other tools own (CUDA, NCCL, PyTorch, launchers) are not registered; code reads them directly with os.environ.get("NAME"), and the name must be in the external-variable allowlist (EXTERNAL_ALLOWLIST in the contract test). When FastVideo sets such a variable for the other tool, it calls envs.set_external, envs.setdefault_external, or envs.unset_external, and the name must be in EXTERNAL_WRITE_ALLOWLIST. Variables that FastVideo's CI and CI tooling define (for example TEST_SCOPE and PERF_RUN_SOURCE) keep their names, and test code under fastvideo/tests/ reads them directly; they are listed in CI_ONLY_VARIABLES in the contract test, together with the file that sets each one.
2. Read with envs.NAME.get(), write with envs.NAME.set(), and change a value in tests with envs.NAME.override(). Each type has one parsing rule. A value that the rule rejects raises fastvideo.envs.EnvVarError instead of falling back to the default.
3. Name FastVideo variables with the FASTVIDEO_ prefix. The second word states the purpose where one applies: ENABLE_, DISABLE_, USE_, FORCE_, DEBUG_, TEST_. Variables that only tests read use FASTVIDEO_TEST_, for example FASTVIDEO_TEST_SD35_MODEL_DIR, and the category test.
4. Keep a renamed variable as a deprecated alias until the next minor release. Setting the old name logs a warning. Delete a variable that no code reads, and list it in DEPRECATED_VARIABLES so that setting it logs a warning.
5. Give each setting one source: an argument or an environment variable. Settings that users change per deployment are arguments (CLI or YAML). Expert switches, emergency off switches, and debugging and test switches are environment variables.
6. Read variables inside functions. envs.NAME.get() runs when the function runs, so a changed value takes effect without re-importing a module. Module level, class bodies, decorators, and default argument values run at import time.
7. Do not write the environment to pass values between parts of FastVideo. Pass an argument instead. Tests use envs.NAME.override(), and envs.override_external() for variables outside the registry; both restore the previous value.

Field types¶

A default can be a zero-argument function; get() calls it on each read while the variable is unset. The path roots use this to follow XDG_CONFIG_HOME and XDG_CACHE_HOME.

Using a field without a method, as in if envs.FASTVIDEO_FA4:, raises TypeError.

Add a variable¶

1. Declare the variable in the matching section of fastvideo/envs.py:

   FASTVIDEO_DEBUG_MY_STAGE = EnvBool(False, category="debug", doc="Log the inputs of MyStage.")
   

   The category is one of the values in envs.CATEGORIES.

2. Read the variable inside a function:

   import fastvideo.envs as envs
   
   def forward(self, batch):
       if envs.FASTVIDEO_DEBUG_MY_STAGE.get():
           logger.info("MyStage inputs: %s", batch.keys())
   

3. Regenerate the table at the end of this page:

   python fastvideo/tests/contract/test_env_policy.py
   

4. Run the contract test:

   pytest fastvideo/tests/contract/test_env_policy.py
   

In a test, change the value with override, which restores the previous value on exit:

with envs.FASTVIDEO_DEBUG_MY_STAGE.override(True):
    run_stage()

For a variable outside the registry, such as MASTER_PORT or TEST_SCOPE, use envs.override_external. To keep an override until the end of a test, enter it through the env_overrides fixture from fastvideo/tests/conftest.py, which restores every value at teardown:

def test_my_stage(env_overrides):
    env_overrides.enter_context(envs.FASTVIDEO_DEBUG_MY_STAGE.override(True))
    env_overrides.enter_context(envs.override_external("MASTER_PORT", "29512"))
    run_stage()

In test code under fastvideo/tests/, override_external accepts any name that code may read directly (EXTERNAL_ALLOWLIST, CI_ONLY_VARIABLES) or that is in EXTERNAL_WRITE_ALLOWLIST. Library code may write only the names in EXTERNAL_WRITE_ALLOWLIST.

Rename or remove a variable¶

To rename a variable, declare it under the new name and list the old name in deprecated_names:

FASTVIDEO_LTX2_USE_DISTILLED_SIGMAS = EnvBool(True,
                                              category="sampling",
                                              doc="...",
                                              deprecated_names=("LTX2_USE_DISTILLED_SIGMAS", ))

get() reads an old name only when the new name is unset, and logs a warning once. Update the uses of the old name in examples/, scripts/, docs/, apps/, and the tests in the same pull request. Delete the old name in the next minor release.

To remove a variable that no code reads, delete its entry and add the name to DEPRECATED_VARIABLES in fastvideo/envs.py with a reason. FastVideoArgs calls envs.warn_deprecated_variables(), which logs a warning for each listed variable that is set. Delete the entry in the next minor release.

What the contract test checks¶

The test parses every Python file under fastvideo/, including fastvideo/tests/, with Python's ast module. It skips fastvideo/third_party/, which is copied from upstream projects, and the registry fastvideo/envs.py. It does not check apps/, examples/, scripts/, fastvideo-kernel/, or docs/.

It reports each violation as <path>: <kind> <name>:

The test recognizes os imported under another name, from os import environ, getenv, and a name held in a module-level string constant. Code that reaches the environment through importlib or getattr(os, "environ") is left to code review.

The test also checks that every registry entry has a category from envs.CATEGORIES and a description, and that the table at the end of this page matches the registry.

Known violations. KNOWN_VIOLATIONS in the contract test lists the violations that existed when the policy was introduced. The list only shrinks. A violation that is not in the list fails the test. A listed violation that no longer exists also fails the test, so the fixing pull request deletes its entry.

Registered variables¶

Variables that FastVideo no longer reads; setting one logs a warning: