Configuration

Global configuration in linkml uses pydantic-settings

Sources

Config values can be set (in order of priority from high to low, where higher priorities override lower priorities)

• in the arguments passed to the class constructor (not user configurable)

• in environment variables like export LINKML_LOG_DIR=~/

• in a .env file in the working directory

• in a linkml_config.yaml file in the working directory

• in the tool.linkml.config table in a pyproject.toml file in the working directory

• in the global linkml_config.yaml file in the platform-specific data directory[1] (use linkml config get config_file to find its location)

• the default values in the GlobalConfig model

Parent directories are not checked.

Keys

Prefix

Keys for environment variables (i.e. set in a shell with e.g. export or in a .env file) are prefixed with LINKML_ to not shadow other environment variables. Keys in toml or yaml files are not prefixed with LINKML_ .

Nesting

Keys for nested models are separated by a __ double underscore in .env files or environment variables (eg. LINKML_LOG__DIR)

Keys in toml or yaml files do not have a dunder separator because they can represent the nesting directly (see examples below)

When setting values from the cli, keys for nested models are separated with a ..

Case

Keys are case-insensitive, i.e. these are equivalent::

export LINKML_LOG__DIR=~/
export linkml_log__dir=~/

CLI

Global settings can be gotten and set via the CLI, for example:

Getting values

$ linkml config get
user_dir: /home/runner/.config/linkml
config_file: /home/runner/.config/linkml/linkml_config.yaml
log:
  dir: /home/runner/.local/state/linkml/log
  file_name: linkml.log
...

Index nested config models with .

$ linkml config get log.level
INFO

Setting values

Values are set in the global linkml_config.yaml file with a similar syntax

Note

Values set via the CLI are set in the global linkml_config.yaml file, which is the lowest priority source of settings, and will thus be overridden by any local configs in .env files or otherwise.

$ linkml config set log.level WARNING
Updated linkml config:
key: log.level
value: WARNING
config file: /home/runner/.config/linkml/linkml_config.yaml

$ linkml config get log.level
INFO

Examples

linkml_config.yaml

user_dir: ~/.config/linkml
config_file: linkml_config.yaml
log:
  dir: /var/log/linkml
  level_file: INFO
  level_stream: WARNING
  file_n: 5

env vars

export LINKML_USER_DIR='~/.config/linkml'
export LINKML_CONFIG_FILE='linkml_config.yaml'
export LINKML_LOG__DIR='/var/log/linkml'
export LINKML_LOG__LEVEL_FILE='INFO'
export LINKML_LOG__LEVEL_STREAM='WARNING'
export LINKML_LOG__FILE_N=5

.env file

LINKML_USER_DIR='~/.config/linkml'
LINKML_CONFIG_FILE='linkml_config.yaml'
LINKML_LOG__DIR='/var/log/linkml'
LINKML_LOG__LEVEL_FILE='INFO'
LINKML_LOG__LEVEL_STREAM='WARNING'
LINKML_LOG__FILE_N=5

pyproject.toml

[tool.linkml.config]
user_dir = "~/.config/linkml"
config_file = "linkml_config.yaml"

[tool.linkml.config.log]
dir = "/var/log/linkml"
level_file = "INFO"
level_stream = "WARNING"
file_n = 5

cli

linkml config set user_dir '~/.config/linkml'
linkml config set config_file 'linkml_config.yaml'
linkml config set log.dir '/var/log/linkml'
linkml config set log.level_file 'info'
linkml config set log.level_stream 'warning'
linkml config set log.file_n 5

API

Session-global configuration (see docs/config/index.md for documentation)

class linkml.utils.config.GlobalConfig(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_prefix_target: EnvPrefixTarget | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_nested_max_split: int | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, ...] | None = None, _cli_settings_source: CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | Literal['dual', 'toggle'] | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | Literal['all', 'no_enums'] | None = None, _cli_shortcuts: Mapping[str, str | list[str]] | None = None, _secrets_dir: PathType | None = None, _build_sources: tuple[tuple[PydanticBaseSettingsSource, ...], dict[str, Any]] | None = None, *, user_dir: Path = '/home/runner/.config/linkml', config_file: Path = PosixPath('linkml_config.yaml'), log: LogConfig = LogConfig(dir='/home/runner/.local/state/linkml/log', file_name='linkml.log', level='INFO', level_file='INFO', level_stream='INFO', file_n=5, file_size=4194304))

Global LinkML configuration that determines the behavior of linkml in a given shell session.

Distinct from generator and project configs, which control the behavior of specific generators and projects, respectively.

config_file_is_absolute() → GlobalConfig

If config_file is relative, make it absolute underneath user_dir

model_config: ClassVar[SettingsConfigDict] = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': '.env', 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': '__', 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': 'linkml_', 'env_prefix_target': 'variable', 'extra': 'ignore', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': True, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'pyproject_toml_table_header': ('tool', 'linkml', 'config'), 'secrets_dir': None, 'toml_file': None, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': 'linkml_config.yaml', 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod settings_customise_sources(settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) → tuple[PydanticBaseSettingsSource, ...]

Read config settings from, in order of priority from high to low, where high priorities override lower priorities:

• in the arguments passed to the class constructor (not user configurable)

• in environment variables like export LINKML_LOG_DIR=~/

• in a .env file in the working directory

• in a linkml_config.yaml file in the working directory

• in the tool.linkml.config table in a pyproject.toml file in the working directory

• in the global linkml_config.yaml file in the platform-specific data directory (use linkml config get config_file to find its location)

• the default values in the GlobalConfig model

classmethod user_dir_exists(v: Path) → Path

Ensure user_dir exists, make it otherwise

class linkml.utils.config.LogConfig(*, dir: Path = '/home/runner/.local/state/linkml/log', file_name: str = 'linkml.log', level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR'] = 'INFO', level_file: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR'] | None = None, level_stream: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR'] | None = None, file_n: int = 5, file_size: int = 4194304)

Config params for logging

inherit_base_level() → LogConfig

If loglevels for specific output streams are unset, set from base level

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod uppercase_levels(value: str | None = None) → str | None

Ensure log level strings are uppercased

linkml.utils.config.get_config(reload: bool = False) → GlobalConfig

Get the global linkml configuration

Parameters:

reload (bool) – If True, force reloading the config from disk, clearing the in-memory cached version

---

[1]

These directories come from platformdirs, see their documentation for more info. The default configuration directories for linkml are:

• Linux: ~/.config/linkml/

• Mac: ~/Library/Application Support/linkml/

• Windows: ~\AppData\Local\linkml\linkml\