Skip to content

Configuration

Metaxy can be configured using TOML configuration files, environment variables, or programmatically.

Either TOML-based or environment-based configuration is required to use the Metaxy CLI.

Configuration Priority

When the same setting is defined in multiple places, Metaxy uses the following priority order (highest to lowest):

  1. Explicit arguments - Values passed directly to MetaxyConfig()
  2. Environment variables - Values from METAXY_* environment variables
  3. Configuration files - Values from metaxy.toml or pyproject.toml

Config Discovery

Configuration files are discovered automatically by searching in the current or parent directories. metaxy.toml takes precedence over pyproject.toml.

Templating Environment Variables

Metaxy supports templating environment variables in configuration files using the ${VARIABLE_NAME} syntax.

Example

metaxy.toml
[stores.branch.config]
root_path = "s3://my-bucket/${BRANCH_NAME}"

Configuration Options

Store Configuration

The stores field configures metadata store backends. Each store is defined by:

  • type: Full import path to the store class (e.g., metaxy.ext.metadata_stores.duckdb.DuckDBMetadataStore)
  • config: Dictionary of store-specific configuration options
  • fallback_stores - optional list of store names to pull missing metadata from. Learn more here.

store

Default metadata store to use

Type: str | Default: "dev"

store = "dev"

[tool.metaxy]
store = "dev"

export METAXY_STORE=dev

stores

Named store configurations

Type: dict[str, metaxy.config.StoreConfig]

# Optional
# stores = {}

[tool.metaxy]
# Optional
# stores = {}

export METAXY_STORES=...

migrations_dir

Directory where migration files are stored

Type: str | Default: ".metaxy/migrations"

migrations_dir = ".metaxy/migrations"

[tool.metaxy]
migrations_dir = ".metaxy/migrations"

export METAXY_MIGRATIONS_DIR=.metaxy/migrations

entrypoints

List of Python module paths to load for feature discovery

Type: list[str]

# Optional
# entrypoints = []

[tool.metaxy]
# Optional
# entrypoints = []

export METAXY_ENTRYPOINTS=...

theme

Graph rendering theme for CLI visualization

Type: str | Default: "default"

theme = "default"

[tool.metaxy]
theme = "default"

export METAXY_THEME=default

hash_truncation_length

Truncate hash values to this length.

Type: int | Default: 8

hash_truncation_length = 8

[tool.metaxy]
hash_truncation_length = 8

export METAXY_HASH_TRUNCATION_LENGTH=8

auto_create_tables

Auto-create tables when opening stores. It is not advised to enable this setting in production.

Type: bool | Default: False

auto_create_tables = false

[tool.metaxy]
auto_create_tables = false

export METAXY_AUTO_CREATE_TABLES=false

project

Project name for metadata isolation. Used to scope operations to enable multiple independent projects in a shared metadata store. Does not modify feature keys or table names. Project names must be valid alphanumeric strings with dashes, underscores, and cannot contain forward slashes (/) or double underscores (__)

Type: str | None

# Optional
# project = null

[tool.metaxy]
# Optional
# project = null

export METAXY_PROJECT=...

locked

Whether to raise an error if an external feature doesn't have a matching feature version when syncing external features from the metadata store.

Type: bool | None

# Optional
# locked = null

[tool.metaxy]
# Optional
# locked = null

export METAXY_LOCKED=...

sync

Whether to automatically sync external feature definitions from the metadata during some operations. It's recommended to keep this enabled as it ensures versioning correctness for external feature definitions with a negligible performance impact.

Type: bool | Default: True

sync = true

[tool.metaxy]
sync = true

export METAXY_SYNC=true

metaxy_lock_path

Relative or absolute path to the lock file, resolved from the config file's location.

Type: str | Default: "metaxy.lock"

metaxy_lock_path = "metaxy.lock"

[tool.metaxy]
metaxy_lock_path = "metaxy.lock"

export METAXY_METAXY_LOCK_PATH=metaxy.lock