hao-ai-lab-FastVideo/docs/contributing/env_vars.md

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

Class	Value type	Parsing rule
EnvBool	bool	1, true, yes, on are true; 0, false, no, off, and "" are false.
		Case-insensitive; surrounding whitespace is ignored.
EnvInt	int	int(value)
EnvFloat	float	float(value)
EnvStr	str or None	The raw string. A None default means that the variable has no default.
EnvPath	str or None	The raw string with a leading ~ expanded.
EnvChoice	str	Stripped and lower-cased, then checked against the declared choices.

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>:

Kind	Code that triggers it	Fix
read	os.getenv, os.environ.get, os.environ[...], or	Register the variable and call
	"NAME" in os.environ with a name outside the allowlist, or	envs.NAME.get(). For a variable that
	with a name built at runtime (<dynamic>)	another tool owns, add it to
		EXTERNAL_ALLOWLIST with a reason.
write	os.environ[...] = ..., setdefault, pop, del,	Pass an argument instead. In tests, use
	os.putenv, os.unsetenv, monkeypatch.setenv/delenv,	envs.NAME.override(), or
	or an envs.*_external call with a name that the	envs.override_external() for a variable
	helper does not accept	outside the registry. For a variable that
		another tool reads, call an
		envs.*_external helper and add the name to
		EXTERNAL_WRITE_ALLOWLIST with a reason.
whole-environ	os.environ.copy(), dict(os.environ), iteration,	Read the specific variables that the code
	mock.patch.dict(os.environ, ...), os.environ.update	needs.
bare-field	A registry field used without calling one of its methods,	Call envs.NAME.get().
	as in envs.NAME == "auto" or getter = envs.NAME.get
import-time-read	envs.NAME.get() outside a function	Move the read into the function that uses
		the value.
prefix	A registry entry without the FASTVIDEO_ prefix	Rename the variable and keep the old name in
		deprecated_names.
unread	A registry entry that no code reads with get() or	Delete the variable and add it to
	is_set()	DEPRECATED_VARIABLES.

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

Variable	Type	Default	Category	Description
FASTVIDEO_CONFIG_ROOT	path	computed	path	Root directory for FastVideo configuration files, at runtime and at installation. Defaults to ~/.config/fastvideo, or $XDG_CONFIG_HOME/fastvideo when XDG_CONFIG_HOME is set.
FASTVIDEO_CACHE_ROOT	path	computed	path	Root directory for FastVideo cache files. Defaults to ~/.cache/fastvideo, or $XDG_CACHE_HOME/fastvideo when XDG_CACHE_HOME is set.
FASTVIDEO_REASON1_WEIGHTS_PATH	str	unset	path	Local path or Hugging Face id of Reason1 weights to load instead of the checkpoint's own.
FASTVIDEO_HOST_IP	str	""	distributed	IP address of this node when the node has several network interfaces. Set it on each node for multi-node inference.
FASTVIDEO_LOOPBACK_IP	str	""	distributed	Loopback IP address to use instead of the detected one.
FASTVIDEO_RAY_PER_WORKER_GPUS	float	1.0	distributed	GPUs per Ray worker. A fraction lets Ray schedule several actors on one GPU, so other actors can share the GPUs with FastVideo.
FASTVIDEO_NCCL_SO_PATH	str	unset	distributed	Path to the NCCL library file. Needed because the nccl>=2.19 that PyTorch ships has a bug (https://github.com/NVIDIA/nccl/issues/1234).
FASTVIDEO_HCCL_SO_PATH	str	unset	distributed	Path to the HCCL library file on Ascend NPUs. Deprecated names: HCCL_SO_PATH.
FASTVIDEO_WORKER_MULTIPROC_METHOD	one of spawn, fork, forkserver	spawn	distributed	Multiprocessing start method for worker processes.
FASTVIDEO_EXTERNAL_LAUNCHER	bool	0	distributed	With the default mp backend, offline inference runs SPMD under torchrun or srun: each launched process is one worker joining the env:// rendezvous. All ranks must call generate() together; world rank 0 owns outputs.
FASTVIDEO_ULYSSES_A2A	one of off, auto	off	distributed	Sequence-parallel all-to-all backend. off uses the NCCL path in DistributedAutograd.AllToAll4D. auto uses the fused NVLink kernel when the group is a load-store accessible mesh of 2, 4, 6, or 8 ranks in eager execution, and the NCCL path otherwise.
FASTVIDEO_ULYSSES_A2A_LONG_TRAINING	one of auto, chunked	auto	distributed	Fused Ulysses all-to-all policy for grad-enabled calls whose window exceeds the long-training plane limit. auto keeps the original unchunked transport. chunked uses bounded chunks; validate the recipe's activation memory first.
FASTVIDEO_CONFIGURE_LOGGING	bool	1	logging	Configure logging at import. When true, FastVideo uses its default logging configuration or the file in FASTVIDEO_LOGGING_CONFIG_PATH.
FASTVIDEO_LOGGING_CONFIG_PATH	str	unset	logging	Path to a JSON logging configuration file.
FASTVIDEO_LOGGING_LEVEL	str	INFO	logging	Default logging level.
FASTVIDEO_LOGGING_PREFIX	str	""	logging	Prefix prepended to every log message.
FASTVIDEO_STAGE_LOGGING	bool	0	logging	Log the time that each pipeline stage takes.
FASTVIDEO_LOG_ALL_PROCESSES	bool	0	logging	logger.info logs from every process, ignoring the default local-main-process filter and the main_process_only and local_main_process_only arguments. Read at each call, so it can be set after importing fastvideo. Useful for debugging distributed runs.
FASTVIDEO_ATTENTION_BACKEND	str	unset	attention	Attention backend, as an AttentionBackendEnum name such as TORCH_SDPA, FLASH_ATTN, VIDEO_SPARSE_ATTN, SAGE_ATTN, or SAGE_ATTN_THREE. FastVideoArgs uses it when FastVideoArgs.attention_backend is unset.
FASTVIDEO_FA4	bool	0	attention	The FLASH_ATTN backend uses FlashAttention-4 (flash_attn.cute) instead of FA3 or FA2.
FASTVIDEO_MINIMAX_H3_FA4_PACKED_VARLEN	bool	0	attention	MiniMax-H3 dense DiT self-attention uses the FlashAttention-4 packed-varlen entry point. This changes the floating-point reduction order, so it is an inference-only opt-in.
FASTVIDEO_VSA_PTX_BLACKWELL	bool	0	attention	VIDEO_SPARSE_ATTN_H3 sends tile-64 forwards to the data-center Blackwell (sm_100a / sm_103a) kernel; grad-tracking forwards need its autograd operator, else Triton. fastvideo-kernel reads the same variable with the same rule. Deprecated names: FASTVIDEO_VSA_SM100A.
FASTVIDEO_VSA_TRITON	bool	0	attention	Force the Triton MiniMax-H3 sparse attention kernel. fastvideo-kernel reads the same variable.
FASTVIDEO_NVFP4_FA4	bool	0	attention	FlashAttention-4 quantizes Q and K to NVFP4. An explicit nvfp4_fa4 attention implementation argument takes precedence.
FASTVIDEO_FA4_PV_MODE	one of bf16, fp8	bf16	attention	V dtype on the NVFP4 FlashAttention-4 path (FLASH_ATTN with nvfp4_fa4, ATTN_QAT_INFER on sm_100a/sm_103a): bf16 keeps V in BF16; fp8 casts V to float8 e4m3 without scaling. An explicit fa4_pv_mode attention implementation argument takes precedence.
FASTVIDEO_DISABLE_ATTENTION_COMPILE	bool	1	attention	Keep attention forward out of torch.compile graphs (torch.compiler.disable). Set it to 0 to let attention constructed under that setting be traced. Setting it explicitly to true also blocks regional compile.
FASTVIDEO_MLX_WINDOW	int	0	attention	MLX FastWan windowed attention size in tokens. 0 uses full attention.
FASTVIDEO_MLX_WINDOW_SINK	int	0	attention	Number of sink tokens that MLX windowed attention always attends to.
FASTVIDEO_DISABLE_VSA64_FUSED_LAYOUT	bool	0	attention	VIDEO_SPARSE_ATTN keeps the original tile scatter and BSHD->BHSD transposes instead of the fused Triton layout kernel that no-grad SM100 BF16 head_dim-128 forwards with 64-token tiles use by default.
FASTVIDEO_INFERENCE_TORCH_COMPILE	bool	0	performance	Compile each DiT transformer block with fullgraph torch.compile at inference. Same as FastVideoArgs.inference_torch_compile=True.
FASTVIDEO_VAE_PARALLEL_DECODE	bool	0	performance	MiniMax-H3 VAE decode splits its temporal chunks across the sequence-parallel ranks instead of running serially on the output rank. Same as FastVideoArgs.vae_parallel_decode=True.
FASTVIDEO_VAE_PARALLEL_ENCODE	bool	0	performance	MiniMax-H3 reference-video VAE encode splits its temporal chunks across the sequence-parallel ranks. Same as FastVideoArgs.vae_parallel_encode=True.
FASTVIDEO_VAE_PARALLEL_DECODE_STRATEGY	str	unset	performance	Collective that moves chunks in parallel VAE decode: gather (used when unset) or all_gather.
FASTVIDEO_H3_ENCODER_SPLIT	bool	0	distributed	MiniMax-H3 runs the Qwen3-VL text encoder on a dedicated group of nodes, so the denoising ranks never load it. Same as FastVideoArgs.h3_encoder_split=True.
FASTVIDEO_H3_ENCODER_NODES	int	1	distributed	Number of leading nodes that FASTVIDEO_H3_ENCODER_SPLIT dedicates to the MiniMax-H3 text encoder. Values below 1 count as 1.
FASTVIDEO_MINIMAX_H3_FUSIONS	str	""	performance	MiniMax-H3 inference-only Triton fusions: all, 1, or a comma-separated subset of modulate,qknorm_rope,swiglu. Empty, 0, or none keeps the eager implementation.
FASTVIDEO_MINIMAX_H3_EXACT_KERNELS	str	""	performance	MiniMax-H3 inference-only Triton kernels that reproduce the eager output bit for bit: all, 1, or a comma-separated subset of rope,modulate,swiglu. An op whose FASTVIDEO_MINIMAX_H3_FUSIONS fusion is on keeps the fusion. Empty, 0, or none keeps the eager implementation.
FASTVIDEO_FSDP2_AUTOWRAP	bool	0	performance	FSDP2 shards modules by parameter count instead of the model's shard conditions. Not supported by self-forcing distillation.
FASTVIDEO_FSDP2_MIN_PARAMS	int	10000000	performance	Minimum parameter count of a module that FASTVIDEO_FSDP2_AUTOWRAP shards.
FASTVIDEO_MLX_COMPILE	bool	0	performance	Compile the MLX DiT forward with mx.compile.
FASTVIDEO_MLX_FAST_NORM	bool	0	performance	Use MLX fast normalization kernels.
FASTVIDEO_MLX_DQ_GEMM	str	1	performance	MLX dequantized GEMM for affine-quantized weights: 0 turns it off, 1 uses the measured minimum row count, and an integer sets the minimum row count.
FASTVIDEO_MLX_QUANT_GEMM	str	auto	performance	MLX H3 affine-quantized GEMM path: auto keeps FASTVIDEO_MLX_DQ_GEMM behaviour, dequant always uses dequantize + dense GEMM for wide inputs, qmm always uses mx.quantized_matmul.
FASTVIDEO_LTX2_VAE_CHANNELS_LAST_3D	bool	1	performance	LTX-2 VAE uses the channels_last_3d memory format.
FASTVIDEO_LTX2_DISABLE_AUDIO_AUTOCAST	bool	1	performance	LTX-2 audio decoding runs without CUDA autocast. Deprecated names: LTX2_DISABLE_AUDIO_AUTOCAST.
FASTVIDEO_FLUX2_DISABLE_BF16_REDUCED_PRECISION_REDUCTION	bool	0	performance	Flux denoising disables reduced-precision reductions in bf16 matmuls, which tightens accumulation for the 4-step Klein model.
FASTVIDEO_ENABLE_FUSED_NORM	bool	0	performance	Opt into Wan's inference-only Triton residual + LayerNorm + modulation fusion. Its reduction order changes numerical outputs; the default keeps eager reference compatibility.
FASTVIDEO_DISABLE_FUSED_NORM	bool	0	performance	Turn off the Triton-fused residual + LayerNorm + modulate inference path that Wan blocks opt into, and use the eager path.
FASTVIDEO_FFMPEG_BIN	str	ffmpeg	output	ffmpeg executable used to save video with audio.
FASTVIDEO_VIDEO_CODEC	str	libx264	output	ffmpeg video codec for saved videos.
FASTVIDEO_NVENC_PRESET	str	p1	output	NVENC preset when the codec is an *_nvenc codec.
FASTVIDEO_NVENC_TUNE	str	ull	output	NVENC tune option.
FASTVIDEO_NVENC_RC	str	constqp	output	NVENC rate-control mode.
FASTVIDEO_NVENC_QP	str	28	output	NVENC quantization parameter.
FASTVIDEO_NVENC_BF	str	0	output	NVENC number of B-frames.
FASTVIDEO_X264_PRESET	str	ultrafast	output	x264 preset for non-NVENC codecs.
FASTVIDEO_OUTPUT_PIX_FMT	str	yuv420p	output	ffmpeg pixel format for saved videos.
FASTVIDEO_NVTX_PROFILE	bool	0	profiling	Emit NVTX ranges for external profilers such as Nsight Systems.
FASTVIDEO_TORCH_PROFILER_DIR	path	unset	profiling	Enables the torch profiler and sets the directory for its traces. Must be an absolute path.
FASTVIDEO_TORCH_PROFILER_RECORD_SHAPES	bool	0	profiling	Torch profiler records shapes.
FASTVIDEO_TORCH_PROFILER_WITH_PROFILE_MEMORY	bool	0	profiling	Torch profiler profiles memory.
FASTVIDEO_TORCH_PROFILER_WITH_STACK	bool	0	profiling	Torch profiler captures stacks. Costs about 1.5x runtime and 1.4x trace size.
FASTVIDEO_TORCH_PROFILER_WITH_FLOPS	bool	0	profiling	Torch profiler profiles FLOPs.
FASTVIDEO_TORCH_PROFILE_REGIONS	str	""	profiling	Comma-separated profiler regions to record. The torch profiler requires at least one region.
FASTVIDEO_TRACE_ACTIVATIONS	bool	0	debug	Enable activation trace hooks.
FASTVIDEO_TRACE_LAYERS	str	""	debug	Regex filter for traced module names. Empty means all.
FASTVIDEO_TRACE_STATS	str	abs_mean,sum	debug	Comma-separated activation statistics dumped for each output tensor.
FASTVIDEO_TRACE_OUTPUT	str	/tmp/fv_trace_<pid>.jsonl	debug	JSONL path for activation traces. The literal <pid> is replaced at runtime.
FASTVIDEO_TRACE_STEPS	str	""	debug	Comma-separated denoising step indices. Empty means all.
FASTVIDEO_H3_VSA_PROBE	str	unset	debug	Output directory for the VSA-H3 attention-mass probe, which writes one .pt file per step, layer, and rank. Keeps the model out of regional compile.
FASTVIDEO_LTX2_GEMMA_LOG	str	""	debug	Log file for LTX-2 Gemma text-encoder hidden states, used by parity tests. Deprecated names: LTX2_FASTVIDEO_GEMMA_LOG.
FASTVIDEO_COSMOS25_LOG_KNOBS	bool	0	debug	Log the Cosmos 2.5 latent-preparation conditioning inputs.
FASTVIDEO_CFG_GATE_STEP	float	1.0	sampling	CFG gating fraction in [0, 1]. Steps before len(timesteps) * X run the conditional and unconditional forwards; later steps reuse the cached difference. 1.0 disables gating.
FASTVIDEO_LTX2_USE_DISTILLED_SIGMAS	bool	1	sampling	LTX-2 uses the distilled sigma schedule when FastVideoArgs.ltx2_use_distilled_sigmas is also true. Deprecated names: LTX2_USE_DISTILLED_SIGMAS.
FASTVIDEO_EVAL_CACHE	path	computed	eval	Cache directory for evaluation models and datasets. Defaults to $FASTVIDEO_CACHE_ROOT/eval.
FASTVIDEO_PHYSICS_IQ_BUCKET_URL	str	https://storage.googleapis.com/physics-iq-benchmark	eval	Base URL of the Physics-IQ benchmark bucket.
FASTVIDEO_VBENCH_FULL_INFO_JSON	str	unset	eval	Path to VBench_full_info.json, used instead of the vendored copy. Deprecated names: VBENCH_FULL_INFO_JSON.
FASTVIDEO_FVD_REF_FEATURES	str	unset	eval	Cached reference-feature file for the FVD metric.
FASTVIDEO_FAD_REF_FEATURES	str	unset	eval	Cached reference-feature file for the audio Frechet distance metric.
FASTVIDEO_H3_VSA_FP4	bool	0	attention	Run MiniMax-H3 VSA attention on the block-sparse SageAttention3 FP4 kernel (sm_120 or GB10 sm_121, no-grad, eager inference).
FASTVIDEO_H3_VSA_FP4_PREFIX	one of , fp8, bf16	""	attention	Prefix split for the FP4 sparse attention kernel: keep the dense prefix query tiles (text, reference and audio rows) off the FP4 kernel and run those rows densely with fp8 or bf16 Q/K and bf16 P.V, while video query tiles stay on the FP4 kernel. The fp8 variant is the validated training-time numerics and recovers most of the audio error that FP4 quantizes away. Use 64/128-token tiles. Empty keeps each row on the FP4 kernel.
FASTVIDEO_H3_VSA_FP4_PREFIX_STEPS	int	-1	attention	Number of leading denoising steps that use the FP4 prefix split (see FASTVIDEO_H3_VSA_FP4_PREFIX). -1 applies it to every step; 0 disables it. Early steps set the global structure, so a small value keeps most of the split's quality benefit for a fraction of its cost.
FASTVIDEO_H3_VSA_FP4_TWO_LEVEL_P	bool	0	attention	Quantize the FP4 attention probabilities with the two-level scheme the QAD student trained with (rowmax-derived s_P1, then per-block s_P2) instead of the kernel's single-level default.
FASTVIDEO_H3_VSA_FP4_K_SMOOTH	bool	0	attention	Subtract the per-head key mean before FP4 key quantization, matching the emulator and QAD training numerics. Exact for the softmax; it only changes quantization error.
FASTVIDEO_H3_GATE_CHUNK_ROWS	int	0	performance	Rows per chunk when the VSA FP4 gate branch expands the pooled compression output back to token rows. 0 keeps the single full-size index_select; a positive value caps the transient at chunk_rows*heads*head_dim and is bit-identical.
FASTVIDEO_H3_VSA_FINE_ATTENTION	one of , emulator-mix8, emulator-mixmx, emulator-qk, emulator-bf16	""	attention	Replace tile-128 fine attention, preserving VSA selection and compression, with the Triton emulator of the sparse FP4 kernel: emulator-mix8 = NVFP4 Q/K video, per-token FP8 Q/K prefix; emulator-mixmx = MXFP8 prefix; emulator-qk = NVFP4 Q/K everywhere; emulator-bf16 = unquantized BF16. emulator-bf16 runs on any CUDA GPU. Nonempty overrides take priority over FASTVIDEO_H3_VSA_FP4. Empty keeps the native route.
FASTVIDEO_H3_VSA_HEADS_FIRST_TILE	bool	0	performance	VSA-H3 64/128-token tiles: scatter rows straight into the heads-first layout the sparse kernels read, removing their per-call transpose copy of query, key and value. Bit-identical; no-grad, uncompiled CUDA only.
FASTVIDEO_H3_VSA_TILE_FIRST	bool	0	attention	Single-rank MiniMax-H3 VSA with one tile gather of the block input instead of separate Q/K/V/gate scatters.
FASTVIDEO_H3_VSA_SM89_KERNEL	one of original, bf16, int8	original	attention	Fine-attention kernel for MiniMax-H3 VSA on sm_89: original, bf16, or int8 (INT8 QK, BF16 PV).
FASTVIDEO_H3_SIM_SP_FP8	bool	0	debug	Simulate the FP8 sequence-parallel exchange of the MiniMax-H3 FP4 VSA path on one rank.
FASTVIDEO_H3_FFN_CHUNK_TOKENS	int	0	performance	Inference-only MiniMax-H3 FFN token chunk size; 0 runs the FFN unchunked.
FASTVIDEO_H3_FP8_ATTENTION	bool	0	performance	With NVFP4 layer_profile h3_dit_ffn, run MiniMax-H3 attention projections in FP8.
FASTVIDEO_H3_FP8_GRANULARITY	one of tensor, channel	tensor	performance	FP8 scaling granularity for FASTVIDEO_H3_FP8_ATTENTION.
FASTVIDEO_LORA_SIDE_BRANCH	bool	0	performance	Apply inference LoRA adapters as a bf16 side branch next to every target linear instead of merging them, so the adapter strength can change at runtime. Packed NVFP4 or FP8 linears without their original dense weight always use the side branch.
FASTVIDEO_NVFP4_MM_BACKEND	str	auto	performance	FlashInfer mm_fp4 backend for NVFP4 linears, e.g. auto or cutlass.
FASTVIDEO_NVFP4_MM_ROW_SPLIT	one of off, table, auto	off	performance	Run large cuDNN NVFP4 GEMMs over row chunks where its plan heuristic is slow: off, table (fixed per-shape chunk counts) or auto (time 1/2/4 chunks once per shape; not deterministic across runs).
FASTVIDEO_NVFP4_ACT_AMAX	path	unset	performance	JSON of calibrated NVFP4 input amax per linear, keyed b<block>.<sub> or full prefix; sets a static activation scale.
FASTVIDEO_NVFP4_DYNAMIC_ACT	str	""	performance	NVFP4 linears that derive the activation scale per call: all, or comma-separated layer-name suffixes such as ff.fc_out.
FASTVIDEO_H3_ADALN_CACHE	bool	0	performance	Cache MiniMax-H3 AdaLN modulation per timestep instead of keeping the projection weights resident.
FASTVIDEO_H3_ADALN_TABLE	path	unset	performance	Precomputed MiniMax-H3 AdaLN modulation table; enables the cache and skips loading the AdaLN projection weights.
FASTVIDEO_H3_ADALN_DUMP	path	unset	debug	Write the MiniMax-H3 AdaLN modulation table to this path while sampling.
FASTVIDEO_H3_SPLICE_TRANSFORMER	path	unset	eval	Second MiniMax-H3 transformer that runs the late DMD steps (checkpoint step-splice evaluation).
FASTVIDEO_H3_SPLICE_FROM_STEP	int	4	eval	First denoising step run by FASTVIDEO_H3_SPLICE_TRANSFORMER.
FASTVIDEO_H3_ENCODER_LAYERWISE	bool	0	performance	Stream MiniMax-H3 text-encoder language layers through exact-size pinned host memory (text-only prompts).
FASTVIDEO_H3_ENCODER_FUSED_DEQUANT	bool	0	performance	Expand the serialized NVFP4 MiniMax-H3 text encoder with one fused Triton pass on GPUs without FP4 GEMM.
FASTVIDEO_H3_VAE_TILE_BATCH	int	1	performance	Spatial tiles per MiniMax-H3 video VAE decoder call; 1 decodes per tile.
FASTVIDEO_H3_REF2VA_MEMO_ENTRIES	int	0	performance	Entries in each content-keyed MiniMax-H3 memo of reference encodes (Qwen3-VL Ref2VA presentation, VAE keyframe latents); repeat references are reused exactly. 0 disables.
FASTVIDEO_H3_VAE_TILE_PARALLEL	bool	0	performance	Split MiniMax-H3 VAE spatial tiles (not only temporal chunks) across the sequence-parallel ranks in the parallel decode and keyframe encode; bitwise equal to the serial path.
FASTVIDEO_H3_VAE_NVFP4_FUSED	bool	1	performance	Run NVFP4 MiniMax-H3 VAE decoder blocks through the bit-exact fused Triton kernels at inference.
FASTVIDEO_H3_VAE_NVFP4_CUDA_GRAPH	bool	1	performance	Replay small fused NVFP4 MiniMax-H3 VAE decoder calls (at most four 1797-token tiles) as per-shape CUDA graphs.
FASTVIDEO_H3_VAE_NVFP4_DECODER	path	unset	performance	Exported NVFP4 MiniMax-H3 video decoder (.pt, or .safetensors with bf16 masters or pre-packed NVFP4 weights) that replaces the VAE decoder at load; skips the INT8 ConvRot overlay.
FASTVIDEO_H3_VAE_INT8_OVERLAY	bool	1	performance	Apply the INT8 ConvRot decoder overlay when the MiniMax-H3 VAE folder ships one; 0 decodes with the dense weights.
FASTVIDEO_H3_VAE_INT8_SHARED_QKV	bool	0	performance	Share the INT8 activation rotation and quantization across the MiniMax-H3 VAE Q/K/V projections.
FASTVIDEO_H3_VAE_INT8_TRANSPOSE_VIEW	bool	0	performance	Use transposed weight views in the MiniMax-H3 VAE INT8 projections.
FASTVIDEO_H3_VAE_INT8_FUSED_DEQUANT	bool	0	performance	Fused dequantization epilogue for the MiniMax-H3 VAE INT8 projections.
FASTVIDEO_H3_PINNED_SWAP	bool	1	performance	Swap offloaded MiniMax-H3 modules through exact-size pinned host arenas.
FASTVIDEO_H3_PARK_MODULES	str	unset	performance	Comma-separated MiniMax-H3 denoise modules parked on the host while the text encoder runs, e.g. vae,audio_vae.
FASTVIDEO_LAYERWISE_OFFLOAD_BUFFERS	bool	0	performance	Layerwise offload also streams large buffers such as packed FP4/FP8 weights.
FASTVIDEO_LAYERWISE_RESIDENT_BLOCKS	int	0	performance	Keep the first N layerwise-offloaded blocks resident on the GPU.
FASTVIDEO_H3_SP_PROFILE	bool	0	profiling	CUDA-event spans per stage over one MiniMax-H3 FP4 VSA DiT forward.
FASTVIDEO_H3_CAPTURE_QKV	path	unset	debug	Directory for captured real MiniMax-H3 Q/K/V attention inputs.
FASTVIDEO_CUDA_MEMORY_CAP_GIB	float	0.0	debug	Cap this process's CUDA allocator at this many GiB to emulate a smaller GPU; 0 leaves it uncapped.
FASTVIDEO_MEMORY_REPORT	bool	0	debug	Log bytes held per pipeline component by device and dtype after loading.
FASTVIDEO_TEST_WAN_S2V_MODEL_PATH	path	unset	test	Wan2.2-S2V-14B weights for test_wan_s2v.py; unset means official_weights/Wan2.2-S2V-14B in the repository. Deprecated names: WAN_S2V_MODEL_PATH.
FASTVIDEO_TEST_LTX2_OVERFIT_DATA_DIR	str	data/cats	test	Raw data directory for preprocess_ltx2_overfit.py. Deprecated names: LTX2_OVERFIT_DATA_DIR.
FASTVIDEO_TEST_LTX2_OVERFIT_CAPTION_JSON	str	videos2caption_1_sample.json	test	Caption file, relative to the raw data directory. Deprecated names: LTX2_OVERFIT_CAPTION_JSON.
FASTVIDEO_TEST_LTX2_OVERFIT_VIDEO_SUBDIR	str	video	test	Video subdirectory, relative to the raw data directory. Deprecated names: LTX2_OVERFIT_VIDEO_SUBDIR.
FASTVIDEO_TEST_LTX2_OVERFIT_OUTPUT_DIR	str	data/ltx2_overfit_preprocessed	test	Output directory for preprocess_ltx2_overfit.py. Deprecated names: LTX2_OVERFIT_OUTPUT_DIR.
FASTVIDEO_TEST_LTX2_OVERFIT_MODEL	str	FastVideo/LTX2-Distilled-Diffusers	test	Model repository whose encoders preprocess_ltx2_overfit.py uses. Deprecated names: LTX2_OVERFIT_MODEL.
FASTVIDEO_TEST_LTX2_OVERFIT_NUM_COPIES	int	4	test	Number of copies of the overfit sample in the parquet file. Deprecated names: LTX2_OVERFIT_NUM_COPIES.
FASTVIDEO_TEST_KANDINSKY5_OVERFIT_DATA_DIR	str	data/kandinsky5_overfit	test	Raw data directory for preprocess_kandinsky5_overfit.py. Deprecated names: KANDINSKY5_OVERFIT_DATA_DIR.
FASTVIDEO_TEST_KANDINSKY5_OVERFIT_OUTPUT_DIR	str	data/kandinsky5_overfit_preprocessed	test	Output directory for preprocess_kandinsky5_overfit.py. Deprecated names: KANDINSKY5_OVERFIT_OUTPUT_DIR.
FASTVIDEO_TEST_HUNYUAN15_OVERFIT_DATA_DIR	str	data/hunyuan15_overfit	test	Raw data directory for preprocess_hunyuan15_overfit.py.
FASTVIDEO_TEST_HUNYUAN15_OVERFIT_OUTPUT_DIR	str	data/hunyuan15_overfit_preprocessed	test	Output directory for preprocess_hunyuan15_overfit.py.
FASTVIDEO_TEST_SSIM_REFERENCE_HF_REPO	str	FastVideo/ssim-reference-videos	test	Hugging Face repository that holds the SSIM reference videos. Deprecated names: FASTVIDEO_SSIM_REFERENCE_HF_REPO.
FASTVIDEO_TEST_SSIM_REFERENCE_HF_REPO_TYPE	str	dataset	test	Repository type of FASTVIDEO_TEST_SSIM_REFERENCE_HF_REPO. Deprecated names: FASTVIDEO_SSIM_REFERENCE_HF_REPO_TYPE.
FASTVIDEO_TEST_SSIM_SKIP_REFERENCE_DOWNLOAD	bool	0	test	SSIM tests use local reference videos without downloading. Deprecated names: FASTVIDEO_SSIM_SKIP_REFERENCE_DOWNLOAD.
FASTVIDEO_TEST_SSIM_FULL_QUALITY	bool	0	test	SSIM tests use the full-quality sampling configurations. Deprecated names: FASTVIDEO_SSIM_FULL_QUALITY.
FASTVIDEO_TEST_NIGHTLY	bool	0	test	Run the nightly end-to-end overfit tests. Deprecated names: FASTVIDEO_NIGHTLY.
FASTVIDEO_TEST_ULYSSES_FAULT_RANK	str	unset	test	Rank that fails in the Ulysses fault-injection test. The test sets it for its worker processes. Deprecated names: FASTVIDEO_ULYSSES_FAULT_RANK.
FASTVIDEO_TEST_ULYSSES_FAULT_STAGE	str	unset	test	Stage that fails in the Ulysses fault-injection test. The test sets it for its worker processes. Deprecated names: FASTVIDEO_ULYSSES_FAULT_STAGE.
FASTVIDEO_TEST_GOLDEN_GATE_DIR	str	unset	test	Local directory of golden-gate reference tensors. Deprecated names: FASTVIDEO_GOLDEN_GATE_DIR.
FASTVIDEO_TEST_WAN22_5B_ALLOW_LOW_MEMORY	bool	0	test	Run the MLX Wan2.2 5B real-weights parity test on hosts with little memory. Deprecated names: FASTVIDEO_WAN22_5B_ALLOW_LOW_MEMORY.
FASTVIDEO_TEST_WAN22_5B_ROOT	str	unset	test	Local Wan2.2 5B checkpoint for the MLX real-weights parity test. Deprecated names: FASTVIDEO_WAN22_5B_ROOT.
FASTVIDEO_TEST_GRADNORM_UPDATE	bool	0	test	Gradient-norm regression tests update their references. Deprecated names: FASTVIDEO_GRADNORM_UPDATE.
FASTVIDEO_TEST_FLUX_T2I_MODEL_DIR	str	black-forest-labs/FLUX.1-dev	test	Model for the Flux text-to-image SSIM test. Deprecated names: FLUX_T2I_MODEL_DIR.
FASTVIDEO_TEST_FLUX_TRANSFORMER_PATH	str	unset	test	Local Flux transformer for the Flux transformer test. Deprecated names: FLUX_TRANSFORMER_PATH.
FASTVIDEO_TEST_GEN3C_MODEL_PATH	str	FastVideo/GEN3C-Cosmos-7B-Diffusers	test	Model for the GEN3C SSIM test. Deprecated names: GEN3C_MODEL_PATH.
FASTVIDEO_TEST_GEN3C_IMAGE_PATH	str	unset	test	Input image for the GEN3C SSIM test. Deprecated names: GEN3C_TEST_IMAGE_PATH.
FASTVIDEO_TEST_KANDINSKY5_E2E_NUM_GPUS	int	1	test	GPUs for the Kandinsky5 nightly end-to-end overfit test. Deprecated names: KANDINSKY5_E2E_NUM_GPUS.
FASTVIDEO_TEST_KANDINSKY5_E2E_WRITE_REFERENCE	bool	0	test	The Kandinsky5 nightly end-to-end test writes a missing reference video. Deprecated names: KANDINSKY5_E2E_WRITE_REFERENCE.
FASTVIDEO_TEST_MINIMAX_H3_GATE_GOLDEN_DIR	str	unset	test	Local directory of MiniMax-H3 golden-gate tensors. Deprecated names: MINIMAX_H3_GATE_GOLDEN_DIR.
FASTVIDEO_TEST_MINIMAX_H3_GATE_LAYER	int	0	test	Transformer layer that the MiniMax-H3 golden-gate test checks. Deprecated names: MINIMAX_H3_GATE_LAYER.
FASTVIDEO_TEST_MINIMAX_H3_MODEL_ROOT	str	unset	test	Local MiniMax-H3 checkpoint for the golden-gate test. Deprecated names: MINIMAX_H3_MODEL_ROOT.
FASTVIDEO_TEST_SD35_MODEL_DIR	str	stabilityai/stable-diffusion-3.5-medium	test	Model for the Stable Diffusion 3.5 SSIM test. Deprecated names: SD35_MODEL_DIR.
FASTVIDEO_TEST_TAEH3_REFERENCE_DIR	str	unset	test	Upstream taehv checkout for the MLX TAEH3 parity test. Deprecated names: TAEH3_REFERENCE_DIR.
FASTVIDEO_TEST_WAN_ANIMATE_MODEL_DIR	str	unset	test	Local Wan2.2-Animate-14B checkpoint for the Wan-Animate weight tests. Deprecated names: WAN_ANIMATE_MODEL_PATH.

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

Deprecated variable	Reason
FASTVIDEO_TARGET_DEVICE	no code reads it
FASTVIDEO_USE_PRECOMPILED	no code reads it
FASTVIDEO_RINGBUFFER_WARNING_INTERVAL	no code reads it
FASTVIDEO_ENGINE_ITERATION_TIMEOUT_S	no code reads it
FASTVIDEO_SERVER_DEV_MODE	no code reads it
FASTVIDEO_TEST_DYNAMO_FULLGRAPH_CAPTURE	no code reads it
FASTVIDEO_TRACE_FUNCTION	no code reads it
FASTVIDEO_TEST_DREAMX_WORLD_SSIM_MODEL_PATH	DreamX World was removed
DREAMX_WORLD_SSIM_MODEL_PATH	DreamX World was removed
FASTVIDEO_TEST_DREAMX_WORLD_AR_SSIM_MODEL_PATH	DreamX World was removed
DREAMX_WORLD_AR_SSIM_MODEL_PATH	DreamX World was removed
FASTVIDEO_TEST_GAMECRAFT_MODEL_PATH	HunyuanGameCraft was removed
GAMECRAFT_MODEL_PATH	HunyuanGameCraft was removed
FASTVIDEO_TEST_GLM_IMAGE_LOCAL_WEIGHTS_DIR	GLM-Image was removed
GLM_IMAGE_LOCAL_WEIGHTS_DIR	GLM-Image was removed
FASTVIDEO_TEST_GLM_IMAGE_MODEL_DIR	GLM-Image was removed
GLM_IMAGE_MODEL_DIR	GLM-Image was removed
FASTVIDEO_TEST_LONGCAT_MODEL_ROOT	LongCat was removed
LONGCAT_MODEL_ROOT	LongCat was removed
FASTVIDEO_TEST_ZIMAGE_MODEL_DIR	Z-Image was removed
ZIMAGE_MODEL_DIR	Z-Image was removed
FASTVIDEO_TEST_ZIMAGE_MODEL_REVISION	Z-Image was removed
ZIMAGE_MODEL_REVISION	Z-Image was removed