{"id":2997,"library":"ml-collections","title":"ML Collections","description":"ML Collections is a library of Python collections designed for ML use cases. It provides dict-like data structures, primarily `ConfigDict` and `FrozenConfigDict`, which offer dot-based access, type safety, and other features useful for managing experiment configurations in a structured way. The library is actively maintained, with its current version being 1.1.0, and receives regular updates.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/google/ml_collections","tags":["machine learning","configuration","dict","config","absl-flags","deepmind"],"install":[{"cmd":"pip install ml-collections","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Used for command-line flag definitions and other utilities.","package":"absl-py","optional":false},{"reason":"Used for YAML serialization and deserialization of configurations.","package":"pyyaml","optional":false}],"imports":[{"symbol":"ConfigDict","correct":"from ml_collections import config_dict"},{"symbol":"FrozenConfigDict","correct":"from ml_collections import config_dict"},{"symbol":"FieldReference","correct":"from ml_collections import config_dict"},{"symbol":"DEFINE_config_dict","correct":"from ml_collections import config_flags"},{"symbol":"DEFINE_config_file","correct":"from ml_collections import config_flags"}],"quickstart":{"code":"from ml_collections import config_dict\n\n# Create a ConfigDict\ncfg = config_dict.ConfigDict()\n\n# Assign values with dot notation\ncfg.learning_rate = 0.001\ncfg.optimizer = 'Adam'\ncfg.model = config_dict.ConfigDict()\ncfg.model.name = 'ResNet50'\ncfg.model.num_layers = 50\n\n# Access values\nprint(f\"Learning rate: {cfg.learning_rate}\")\nprint(f\"Model name: {cfg.model.name}\")\n\n# ConfigDicts are type-safe (mostly)\ntry:\n    cfg.learning_rate = 'high' # This will raise a TypeError\nexcept TypeError as e:\n    print(f\"Caught expected error: {e}\")\n\n# Integer can be assigned to float fields\ncfg.weight_decay = 1e-5\ncfg.weight_decay = 0 # This works as int -> float conversion is allowed\nprint(f\"Weight decay: {cfg.weight_decay}\")\n","lang":"python","description":"This example demonstrates how to create a `ConfigDict`, assign and access values using dot notation, and illustrates its type-safe behavior. It also shows the exception for assigning integers to float fields."},"warnings":[{"fix":"Replace `cfg.get_ref('field')` with `cfg.get_oneway_ref('field')` when a one-way dependency is desired.","message":"Using `config_dict.get_ref()` creates a bidirectional dependency. If you change the referenced value, the original value also changes. For one-way references, use `config_dict.get_oneway_ref()` instead.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that assigned values match the initial type of the field, or explicitly cast them if a compatible conversion is desired (e.g., `str(integer_value)`).","message":"ConfigDicts are largely type-safe: once a field is set with a particular type, reassigning a value of an incompatible type (e.g., `int` to a `str` field) will raise a `TypeError`. An exception is made for `int` values being assigned to `float` fields, which are automatically converted.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adhere to the `absl.flags`-like syntax for boolean overrides or use explicit `key=value` assignment.","message":"When using `ml_collections.config_flags` to override boolean values from the command line, the syntax is specific: `--config.boolean_field` sets it to `True`, and `--noconfig.boolean_field` sets it to `False`. Standard `--config.boolean_field=value` (with 'true', 'false', 'True', 'False') is also supported.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid nesting mutable dict-like structures directly within lists/tuples during initial `ConfigDict` construction or ensure a DAG structure. Consider creating nested `ConfigDict` instances explicitly for complex structures.","message":"Initializing a `ConfigDict` with an `initial_dictionary` that contains lists or tuples with nested dictionaries, `ConfigDict`s, or `FieldReference`s directly can lead to errors. The internal reference structure must form a Directed Acyclic Graph (DAG).","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}