Install & Compatibility
Where this runs
tested against v1.11.1 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 2.551s · 178.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 17.6s · import 2.385s · 177MB
183MB installed
● package 183MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SchemaDefinition
✓ from linkml_runtime.linkml_model.meta import SchemaDefinition
✗ from linkml_model.meta import SchemaDefinition
The 'linkml-model' package was deprecated and its functionality absorbed into 'linkml-runtime' from version 1.0.0.
PythonGenerator
✓ from linkml.generators.pythongen import PythonGenerator
YAMLLoader
✓ from linkml_runtime.loaders import YAMLLoader
dump_yaml
✓ from linkml_runtime.utils.datautils import dump_yaml
This quickstart demonstrates how to define a simple LinkML schema as a string, load it, generate Python dataclasses from it, create an instance of a generated class, and then serialize that instance back into YAML. This showcases the core model definition, code generation, and data handling capabilities.
import os
from linkml_runtime.linkml_model.meta import SchemaDefinition
from linkml.generators.pythongen import PythonGenerator
from linkml_runtime.loaders import YAMLLoader
from linkml_runtime.utils.datautils import dump_yaml
# Define a simple LinkML schema in YAML string
schema_content = """
id: http://example.org/my_schema
name: my_schema
description: A simple LinkML schema example
prefixes:
ex: http://example.org/my_schema/
default_prefix: ex
classes:
Person:
slots:
- id
- name
- age
slots:
id:
identifier: true
range: string
name:
range: string
age:
range: integer
minimum_value: 0
"""
# 1. Load the schema definition
loader = YAMLLoader()
schema = loader.loads(schema_content, target_class=SchemaDefinition)
print(f"Successfully loaded schema: {schema.name}")
# 2. Generate Python dataclasses from the schema
gen = PythonGenerator(schema=schema)
python_code = gen.serialize()
# For quickstart, execute generated code in current namespace
# In a real application, you'd write this to a file and import it.
namespace = {}
exec(python_code, namespace)
# Get the generated 'Person' class
Person = namespace['Person']
# 3. Create an instance of the generated class
p = Person(id="P001", name="Alice Smith", age=30)
print(f"Created person instance: {p.name}")
# 4. Dump the instance to YAML
yaml_output = dump_yaml(p)
print("\n--- Generated YAML output ---")
print(yaml_output)
linkml --version
Debug
Known issues
breakingLinkML underwent a significant rewrite with version 1.0.0. The previous `linkml-model` package was absorbed, and many internal APIs, command-line interface, and generator outputs changed. This is a major breaking change for users upgrading from pre-1.0.0 versions.fixRefer to the official LinkML migration guides and release notes for version 1.0.0. Carefully check import paths (e.g., `linkml_runtime` vs `linkml-model`) and update CLI commands.
affects: <1.0.0 to >=1.0.0
gotchaThe separation of `linkml-runtime` and `linkml` can be confusing. `linkml-runtime` contains core metamodel definitions (like `SchemaDefinition`) and utilities (loaders, dumpers, validators), while `linkml` contains generators and the CLI. Incorrect imports are common.fixEnsure you are importing from the correct package: `linkml_runtime.linkml_model.meta` for schema definitions and `linkml.generators` for generators, `linkml_runtime.loaders` for loaders, etc.
affects: All versions >=1.0.0
gotchaSchema definition syntax, while generally stable, can have minor evolutions (e.g., new keywords, changes in range handling) between releases. Older schemas might require slight adjustments to work with newer LinkML versions.fixAlways validate your LinkML schema using `linkml validate your_schema.yaml` after upgrading LinkML. Consult release notes for specific schema syntax changes.
affects: All versions
gotchaThe output of generators (e.g., `PythonGenerator`, `JSONGenerator`) can change across versions, particularly around how inheritance, types, defaults, and prefixes are represented. This can break downstream code or systems that rely on the exact structure of generated artifacts.fixPin your LinkML version if strict consistency of generated output is critical for your project. After upgrading, always regenerate artifacts and perform regression testing on consuming applications.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'linkml_model'
Attempting to import from the deprecated 'linkml-model' package, which was removed in LinkML 1.0.0 and integrated into 'linkml-runtime'.
fixUpdate your import statements. For example, `from linkml_model.meta import SchemaDefinition` should become `from linkml_runtime.linkml_model.meta import SchemaDefinition`.
linkml_runtime.utils.validation.ValidationError: Value '...' is not of type '...'
Data being processed does not conform to the types or constraints (e.g., range, minimum_value, pattern) defined in your LinkML schema.
fixReview your data and the corresponding LinkML schema definition. Ensure data types match the `range` definitions and that values respect any specified constraints. Use `linkml validate` on your data against your schema for detailed error messages.
linkml_runtime.utils.generator.GeneratorException: Cannot find target class for generation: 'MyClassName'
The PythonGenerator (or other generators) cannot locate a class named 'MyClassName' within the loaded schema. This can happen due to typos, incorrect prefix resolution, or if the class is not properly defined.
fixVerify that 'MyClassName' is correctly spelled and defined in your LinkML schema. Check the schema's `id`, `name`, `prefixes`, and `default_prefix` to ensure correct resolution of class names.
Upgrade
Version history
1.11.1latest on PyPI · released May 20, 2026
Audit
Dependencies
linkml-runtimerequiredProvides core data structures, utilities, and the LinkML metamodel. It is a fundamental dependency for LinkML.
pydanticoptionalUsed by PythonGenerator for generating Pydantic-compatible classes, which offers robust data validation and serialization features.