> For the complete documentation index, see [llms.txt](https://docs.modular.com/llms.txt). > Markdown versions of all pages are available by appending .md to any URL (e.g. /max/get-started.md). # Environment variables This page documents all environment variables you can use to configure MAX behavior. These variables control server settings, logging, telemetry, performance, and integrations. ## How to set environment variables You can set environment variables in several ways: ```bash # Export in your shell export MAX_SERVE_HOST="0.0.0.0" # Pass to Docker container docker run --env "MAX_SERVE_HOST=0.0.0.0" modular/max-nvidia-full:latest ... # Use a .env file in your working directory echo "MAX_SERVE_HOST=0.0.0.0" >> .env ``` ### Configuration precedence When the same setting is configured in multiple places, the following precedence applies (highest to lowest): 1. **CLI flags or direct Python initialization**: For example, `--port 8080` or `Settings(MAX_SERVE_PORT=8080)`. CLI flags are passed directly to the `Settings` constructor, so they have the same precedence as direct Python initialization. 2. **Environment variables**: `export MAX_SERVE_HOST="0.0.0.0"` 3. **`.env` file values**: Values defined in a `.env` file in your working directory :::note Environment variables must use the exact names documented below. ::: ## Serving These variables configure the MAX model serving behavior. For more information on serving a model with MAX, explore the [text to text](https://docs.modular.com/max/inference/text-to-text.md) and [image and video to text](https://docs.modular.com/max/inference/image-to-text.md) guides. | Variable | Description | Values | Default | |-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|---------------------| | `MAX_SERVE_HOST` | Hostname for the MAX server | String | `0.0.0.0` | | `MAX_SERVE_PORT` | Port for serving MAX | Integer | `8000` | | `MAX_SERVE_METRICS_ENDPOINT_PORT` | Port for the Prometheus metrics endpoint | Integer | `8001` | | `MAX_SERVE_ALLOWED_IMAGE_ROOTS` | Allowed root directories for `file://` URI access | Comma-separated paths | Empty | | `MAX_SERVE_MAX_LOCAL_IMAGE_BYTES` | Maximum size in bytes for local image files | Integer | `20971520` (20 MiB) | | `MAX_SERVE_API_TYPES` | Configures which API types MAX serve exposes. Accepts a JSON array of API type strings (e.g., `'["responses"]'`). Use this to enable the [Responses API](https://docs.modular.com/max/inference/image-generation.md) for tasks like image generation. | JSON array string | None | ## Logging These variables control logging behavior and verbosity. You can read more about logs when using the [MAX container](https://docs.modular.com/max/container.md#logs). | Variable | Description | Values | Default | |--------------------------------|----------------------------------------------------------------|-------------------------------------------------|---------| | `MAX_SERVE_LOGS_CONSOLE_LEVEL` | Console log verbosity level | `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG` | `INFO` | | `MODULAR_STRUCTURED_LOGGING` | Enable JSON-formatted structured logging for deployed services | `0`, `1` | `1` | | `MAX_SERVE_LOGS_FILE_PATH` | Path to write log files | File path | None | | `MAX_SERVE_LOG_PREFIX` | Prefix to prepend to all log messages | String | None | ## Telemetry and metrics These variables control telemetry collection and metrics reporting. For more information, read about [MAX container telemetry](https://docs.modular.com/max/container.md#telemetry). | Variable | Description | Values | Default | |-------------------------------|-------------------------------------------------------------------|-----------------------------|---------| | `MAX_SERVE_DISABLE_TELEMETRY` | Disable remote telemetry collection | `0`, `1` | `0` | | `MODULAR_USER_ID` | User identifier for telemetry (e.g., your company name) | String | None | | `MAX_SERVE_DEPLOYMENT_ID` | Deployment identifier for telemetry (e.g., your application name) | String | None | | `MAX_SERVE_METRIC_LEVEL` | Level of detail in metrics emitted | `NONE`, `BASIC`, `DETAILED` | `BASIC` | ## Debugging The `MODULAR_DEBUG` environment variable enables one or more MAX debugging options. Set it to a comma-separated list of option names, using `name=value` for options that take a value: ```bash export MODULAR_DEBUG=nan-check,assert-level=all ``` This table includes all options you can add to `MODULAR_DEBUG`: | Option | Description | Type | Accepted values | Default | |----------------------------|---------------------------------------------------------------------------------------------------------------|---------|----------------------------------------------------------|-----------| | `sensible` | Enable a curated default debugging set | Boolean | N/A | `false` | | `nan-check` | Insert NaN/Inf checks on a sampled subset of floating-point kernel outputs (see `nan-check-stride`) | Boolean | N/A | `false` | | `nan-check-stride` | When `nan-check` is enabled, check one of every N floating-point kernel outputs. Set to `1` for full coverage | Integer | Positive integer (≥1) | `20` | | `uninitialized-read-check` | Detect reads of uninitialized memory | Boolean | N/A | `false` | | `device-sync-mode` | Force synchronous GPU execution for debugging | Boolean | N/A | `false` | | `stack-trace-on-error` | Show Mojo stack traces on runtime errors | Boolean | N/A | `false` | | `stack-trace-on-crash` | Show Mojo stack traces on crashes | Boolean | N/A | `false` | | `source-tracebacks` | Include Python source locations in error messages | Boolean | N/A | `false` | | `op-log-level` | Log level for op-level execution tracing | String | `trace`, `debug`, `info`, `warning`, `error`, `critical` | `off` | | `assert-level` | Assertion level for the Mojo standard library | String | `none`, `warn`, `safe`, `all` | `none` | | `print-style` | Output format for tensor debug printing | String | `compact`, `full`, `binary`, `binary_max_checkpoint` | `compact` | | `ir-output-dir` | Directory where MAX dumps intermediate compiler IR | Path | Filesystem path | `unset` | ## Profiling For GPU profiling details, see [GPU profiling with Nsight Systems](https://docs.modular.com/max/gpu-system-profiling.md). | Variable | Description | Values | Default | |----------------------------|--------------------------------------|-------------------------|---------| | `MODULAR_ENABLE_PROFILING` | Enable runtime profiling and tracing | `off`, `on`, `detailed` | `off` | ## Performance and caching The following variables configure caching and memory behavior. | Variable | Description | Values | Default | |-----------------------------|------------------------------------------------------------------------------------------------|-----------------|---------------------------------| | `MODULAR_MAX_CACHE_DIR` | Directory to save MAX model cache for reuse | Path | `$MODULAR_CACHE_DIR/.max_cache` | | `MODULAR_CACHE_DIR` | Configure cache directory for all Modular filesystems | Path | See note below | | `MODULAR_MAX_SHM_WATERMARK` | Percentage of `/dev/shm` to allocate for shared memory. Set to `0.0` to disable shared memory. | Float (0.0–1.0) | `0.9` | :::note The default search paths take the following precedence: 1. When the `MODULAR_HOME` environment variable is set `$MODULAR_HOME/cache` is used. 2. If `$HOME/.modular` exists then `$HOME/.modular` is used. 3. Follow the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/latest/). When `XDG_CACHE_HOME` is set, `$XDG_CACHE_HOME/modular` is used; otherwise the default value `$HOME/.cache/modular` is used. ::: ## Weight loading The following variable controls how MAX handles dtype mismatches when loading model weights from a checkpoint. | Variable | Description | Values | Default | |-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|---------| | `MODULAR_AUTO_CAST_WEIGHTS` | Auto-cast loaded weights between `float32` and `bfloat16` when checkpoint and module dtypes mismatch (shape must match). Other dtype mismatches still raise. | `true`, `false` | `true` | ## Hugging Face Configure your Hugging Face integration with the following environment variable: | Variable | Description | Values | Default | |------------|--------------------------------------------------------------|--------|---------| | `HF_TOKEN` | Hugging Face authentication token for accessing gated models | String | None | ## Related resources - [MAX container](https://docs.modular.com/max/container.md) - Deploy MAX with Docker - [`max serve` CLI](https://docs.modular.com/max/cli/serve.md) - Command-line options for serving