Environment Variables

How to control ZenML behavior with environmental variables.

There are a few pre-defined environmental variables that can be used to control the behavior of ZenML. See the list below with default values and options:

Logging verbosity

export ZENML_LOGGING_VERBOSITY=INFO

Choose from INFO, WARN, ERROR, CRITICAL, DEBUG.

Console logging format

export ZENML_CONSOLE_LOGGING_FORMAT=console

Choose from console (default), json, or any valid Python %-style logging format string such as %(asctime)s - %(message)s for custom console output. The console format uses a default compact layout for client-side INFO+ logs and full structured text layout for DEBUG and server logs. The json format emits JSON formatted console/stdout logs.

This controls terminal log formatting only; stored logs keep their raw message and structured metadata. The older ZENML_LOGGING_FORMAT environment variable is still supported as a deprecated alias.

See this page for more information.

Disable step logs

Usually, ZenML stores step logs in the artifact store, but this can sometimes cause performance bottlenecks, especially if the code utilizes progress bars.

If you want to configure whether logged output from steps is stored or not, set the ZENML_DISABLE_STEP_LOGS_STORAGE environment variable to true. Note that this will mean that logs from your steps will no longer be stored and thus won't be visible on the dashboard anymore.

export ZENML_DISABLE_STEP_LOGS_STORAGE=true

ZenML repository path

To configure where ZenML will install and look for its repository, set the environment variable ZENML_REPOSITORY_PATH.

export ZENML_REPOSITORY_PATH=/path/to/somewhere

Analytics

Please see our full page on what analytics are tracked and how you can opt out, but the quick summary is that you can set this to false if you want to opt out of analytics.

export ZENML_ANALYTICS_OPT_IN=false

Debug mode

Setting to true switches to developer mode:

export ZENML_DEBUG=true

Active stack

Setting the ZENML_ACTIVE_STACK_ID to a specific UUID will make the corresponding stack the active stack:

export ZENML_ACTIVE_STACK_ID=<UUID-OF-YOUR-STACK>

Prevent pipeline execution

When true, this prevents a pipeline from executing:

export ZENML_PREVENT_PIPELINE_EXECUTION=false

Disable rich traceback

Set to false to disable the rich traceback:

export ZENML_ENABLE_RICH_TRACEBACK=true

Disable colorful logging

Console logs use colors by default. If you wish to disable colorful logging, set the following environment variable:

ZENML_LOGGING_COLORS_DISABLED=true

Note that setting this on the client environment (e.g. your local machine which runs the pipeline) will automatically disable colorful logging on remote orchestrators. If you wish to disable it locally, but turn on for remote orchestrators, you can set the ZENML_LOGGING_COLORS_DISABLED environment variable in your orchestrator's environment as follows:

docker_settings = DockerSettings(environment={"ZENML_LOGGING_COLORS_DISABLED": "false"})

# Either add it to the decorator
@pipeline(settings={"docker": docker_settings})
def my_pipeline() -> None:
    my_step()

# Or configure the pipelines options
my_pipeline = my_pipeline.with_options(
    settings={"docker": docker_settings}
)

Server OpenTelemetry export

Set ZENML_SERVER_OTEL_EXPORTER_OTLP_ENDPOINT to export ZenML server traces, metrics, and logs to an OpenTelemetry-compatible backend using OTLP/HTTP. The standard OTEL_EXPORTER_OTLP_ENDPOINT environment variable is also supported as a fallback:

export ZENML_SERVER_OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
# OR
# export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318

The endpoint should be the base OTLP/HTTP endpoint. ZenML appends /v1/traces, /v1/metrics, and /v1/logs for each signal. Standard per-signal OTLP/HTTP endpoint variables are also supported and take precedence:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4318/v1/traces
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://otel-collector:4318/v1/metrics
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://otel-collector:4318/v1/logs

You can use the matching ZenML-specific names instead: ZENML_SERVER_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, ZENML_SERVER_OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, and ZENML_SERVER_OTEL_EXPORTER_OTLP_LOGS_ENDPOINT.

If no base or per-signal endpoint is set, server OpenTelemetry instrumentation is disabled.

Each signal is enabled by default when the endpoint is configured. You can disable individual signals with:

export ZENML_SERVER_OTEL_TRACES_ENABLED=false
export ZENML_SERVER_OTEL_METRICS_ENABLED=false
export ZENML_SERVER_OTEL_LOGS_ENABLED=false

You can also customize the service name reported in OpenTelemetry resource attributes. The standard OTEL_SERVICE_NAME environment variable is supported as well as a fallback:

export ZENML_SERVER_OTEL_SERVICE_NAME=zenml-server
# OR
# export OTEL_SERVICE_NAME=zenml-server

Standard OTLP headers, timeout, compression, trace sampler, and resource attribute environment variables are handled by the OpenTelemetry Python SDK and OTLP/HTTP exporters where supported. OTLP/gRPC protocol environment variables are not supported because ZenML configures OTLP/HTTP exporters directly. You can read more about the OpenTelemetry environment variables and SDK configuration here.

Disable stack validation

If you wish to disable stack validation, set the following environment variable:

ZENML_SKIP_STACK_VALIDATION=true

Ignore untracked code repository files

When using code repositories, ZenML will by default require the local checkout to have no uncommitted or untracked files in order to use the code repository to track the commit and download files. If you want to ignore untracked files, you can set the ZENML_CODE_REPOSITORY_IGNORE_UNTRACKED_FILES environment variable to True. When doing this, you're responsible that the files committed to the repository includes everything necessary to run your pipeline.

ZenML global config path

To set the path to the global config file, used by ZenML to manage and store the state for a number of settings, set the environment variable as follows:

export ZENML_CONFIG_PATH=/path/to/somewhere

CLI output formatting

Default output format

Set the default output format for all CLI list commands:

export ZENML_DEFAULT_OUTPUT=json

Choose from table (default), json, yaml, csv, or tsv. This applies to commands like zenml stack list, zenml pipeline list, etc.

Terminal width override

Override the automatic terminal width detection for table rendering:

export ZENML_CLI_COLUMN_WIDTH=120

This is useful when running ZenML in CI/CD environments or when you want to control table formatting regardless of your terminal size.

Server configuration

For more information on server configuration, see the ZenML Server documentation for more, especially the section entitled "ZenML server configuration options".

Client configuration

Setting the ZENML_STORE_URL, ZENML_STORE_API_KEY and ZENML_ACTIVE_PROJECT_ID environment variables automatically connects your ZenML Client to the specified server for a specific project. This method is particularly useful when you are using the ZenML client in an automated CI/CD workload environment like GitHub Actions or GitLab CI or in a containerized environment like Docker or Kubernetes:

export ZENML_STORE_URL=https://...
export ZENML_STORE_API_KEY=<API_KEY>
export ZENML_ACTIVE_PROJECT_ID=<PROJECT_ID>