Skip to content

Configuration

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

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

Configuration files are discovered automatically by searching in the current or parent directories.

Configuration Options

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 (minimum 8 characters).

Type: int | None

# Optional
# hash_truncation_length = null

[tool.metaxy]
# Optional
# hash_truncation_length = null

export METAXY_HASH_TRUNCATION_LENGTH=...

auto_create_tables

Auto-create tables when opening stores (development/testing only). WARNING: Do not use in production. Use proper database migration tools like Alembic.

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 | Default: "default"

project = "default"

[tool.metaxy]
project = "default"

export METAXY_PROJECT=default

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.metadata_store.duckdb.DuckDBMetadataStore)
  • config: Dictionary of store-specific configuration options

Example: Multiple Stores with Fallback Stores

# Default store to use
store = "dev"

# Development store (in-memory) with fallback to production
[stores.dev]
type = "metaxy.metadata_store.duckdb.DuckDBMetadataStore"
[stores.dev.config]
db_path = ":memory:"
fallback_stores = ["prod"]

# Production store
[stores.prod]
type = "metaxy.metadata_store.duckdb.DuckDBMetadataStore"
[stores.prod.config]
db_path = "s3://my-bucket/metadata.duckdb"

[tool.metaxy]
store = "dev"

[tool.metaxy.stores.dev]
type = "metaxy.metadata_store.duckdb.DuckDBMetadataStore"
[tool.metaxy.stores.dev.config]
db_path = ":memory:"
fallback_stores = ["prod"]

[tool.metaxy.stores.prod]
type = "metaxy.metadata_store.duckdb.DuckDBMetadataStore"
[tool.metaxy.stores.prod.config]
db_path = "s3://my-bucket/metadata.duckdb"

Configuring Metadata Stores

Configuration options for metadata stores can be found at the respective store documentation page.

Configuring Metaxy Plugins

Configuration options for Metaxy plugins can be found at the respective plugin documentation page.