Registry / ai-ml / ml-collections

ml-collections

library1.1.0pypypi✓ verified 24d ago

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.

ai-ml serialization

pip install ml-collections

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · ML-COLLECTIONS

ml-collections

ai-mlpythonv1.1.0

Install

2.0s avg

Import

382ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.396s · 21.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.0s · import 0.368s · 23MB

20MB installed

● package 20MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ConfigDict

✓ from ml_collections import config_dict

FrozenConfigDict

✓ from ml_collections import config_dict

FieldReference

✓ from ml_collections import config_dict

DEFINE_config_dict

✓ from ml_collections import config_flags

DEFINE_config_file

✓ from ml_collections import config_flags

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.

from ml_collections import config_dict # Create a ConfigDict cfg = config_dict.ConfigDict() # Assign values with dot notation cfg.learning_rate = 0.001 cfg.optimizer = 'Adam' cfg.model = config_dict.ConfigDict() cfg.model.name = 'ResNet50' cfg.model.num_layers = 50 # Access values print(f"Learning rate: {cfg.learning_rate}") print(f"Model name: {cfg.model.name}") # ConfigDicts are type-safe (mostly) try: cfg.learning_rate = 'high' # This will raise a TypeError except TypeError as e: print(f"Caught expected error: {e}") # Integer can be assigned to float fields cfg.weight_decay = 1e-5 cfg.weight_decay = 0 # This works as int -> float conversion is allowed print(f"Weight decay: {cfg.weight_decay}")

Debug

Known issues

gotchaUsing `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.

fix

Replace `cfg.get_ref('field')` with `cfg.get_oneway_ref('field')` when a one-way dependency is desired.

affects: All versions

gotchaConfigDicts 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.

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)`).

affects: All versions

gotchaWhen 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.

fix

Adhere to the `absl.flags`-like syntax for boolean overrides or use explicit `key=value` assignment.

affects: All versions

breakingInitializing 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).

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.

affects: All versions

Errors

Common errors & fixes

AttributeError: 'ConfigDict' object has no attribute 'some_field_name'

This error occurs when attempting to access or assign a field that does not exist on a ml-collections.ConfigDict, or when trying to add a new field while the ConfigDict is in a locked state (by default, new fields cannot be added after initialization without explicitly unlocking).

fix

Ensure the field name is correct. If you intend to add a new field or modify a locked ConfigDict, use the `with cfg.unlocked():` context manager, or call `cfg.unlock()` and `cfg.lock()` explicitly.

TypeError: 'new_value' is of original type <class 'str'> and cannot be casted to type <class 'int'>

ml-collections.ConfigDict is type-safe. Once a field's type is inferred from its initial assignment, you cannot assign a value of an incompatible type to that field.

fix

Assign a value that is compatible with the field's original type. If you genuinely need to change the type, you can temporarily disable type safety using the `with cfg.ignore_type():` context manager, or delete the field and re-add it with the new type (if the ConfigDict is unlocked).

TypeError: 'FrozenConfigDict' object does not support item assignment

ml-collections.FrozenConfigDict instances are immutable, meaning their contents cannot be changed after creation. Any attempt to modify a field or add a new one will raise this error.

fix

To make changes, you must create a new FrozenConfigDict with the desired modifications, or convert the FrozenConfigDict to a mutable ConfigDict using `.as_configdict()`, make your changes, and then convert it back to a FrozenConfigDict if immutability is still required.

ValueError: Bad FrozenConfigDict initialization: Cannot contain a dict, ConfigDict, or FieldReference within a list or tuple.

FrozenConfigDict enforces deep immutability. When initializing it, lists and tuples within the configuration cannot directly contain mutable types like standard Python dictionaries, ConfigDicts, or FieldReferences, as these could allow for mutation of the FrozenConfigDict.

fix

Ensure that any nested dictionaries or ConfigDicts within lists or tuples are converted to FrozenConfigDicts *before* being used in the initialization of the parent FrozenConfigDict. Lists and tuples themselves should only contain other immutable types or already-frozen ConfigDicts.

Upgrade

Version history

1.1.0latest on PyPI · released Apr 17, 2025

Audit

Dependencies

absl-pyrequiredUsed for command-line flag definitions and other utilities.

pyyamlrequiredUsed for YAML serialization and deserialization of configurations.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/google/ml_collections ↗

packagehttps://pypi.org/project/ml-collections/ ↗

docshttps://ml-collections.readthedocs.io ↗