Install & Compatibility
Where this runs
tested against v2.2 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.481s · 64MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.4s · import 0.426s · 67MB
65MB installed
● package 65MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Constructor
✓ from yaml_include import Constructor
✗ from yamlinclude import YamlIncludeConstructor
The top-level package and main constructor class were renamed in version 2.0. The old import `yamlinclude` is no longer valid.
yaml_include
✓ import yaml_include
✗ import yamlinclude
The package namespace changed from `yamlinclude` to `yaml_include` in version 2.0. Importing the old name will result in an `ImportError`.
This quickstart demonstrates how to use `pyyaml-include` to include one YAML file (`database.yml`) into another (`config.yml`). It involves creating an instance of `yaml_include.Constructor` and registering it with a `PyYAML` loader (e.g., `yaml.FullLoader`) for a custom `!inc` tag. The example then loads the main configuration, which resolves the included file content.
import yaml
import yaml_include
import os
# Create dummy YAML files for the example
with open("database.yml", "w") as f:
f.write("host: localhost\nport: 5432\nname: mydb\n")
with open("config.yml", "w") as f:
f.write("database: !inc database.yml\napp:\n name: MyApp\n")
# Register the include tag with a YAML Loader
# It is recommended to use FullLoader for most use cases with unknown sources
yaml.add_constructor("!inc", yaml_include.Constructor(), yaml.FullLoader)
# Load the main YAML file
with open('config.yml', 'r') as f:
data = yaml.full_load(f)
print(data)
# Expected output: {'database': {'host': 'localhost', 'port': 5432, 'name': 'mydb'}, 'app': {'name': 'MyApp'}}
# Clean up dummy files
os.remove("database.yml")
os.remove("config.yml")
Debug
Known issues
breakingVersion 2.0 introduced significant breaking changes, including a change in the package's import namespace from `yamlinclude` to `yaml_include` and the core `YamlIncludeConstructor` class being renamed to `Constructor`. Code written for `v1.x` is not directly compatible with `v2.x`.fixUpdate all `import` statements and class references from `yamlinclude` to `yaml_include` and `YamlIncludeConstructor` to `Constructor`.
affects: >=2.0.0
breakingFuture versions (e.g., v2.3 and beyond) are expected to drop support for Python 3.8 and below. While v2.2 still supports Python >=3.8, plan to upgrade your Python environment if using older versions.fixEnsure your project runs on Python 3.9 or newer to maintain compatibility with future `pyyaml-include` releases.
affects: >=2.3.0 (planned)
gotchaUsing shell-style wildcards (`**`, `*`, `?`) in include paths, especially with large directory trees or remote filesystems, can lead to performance issues and high memory consumption. All matched files are fully loaded into memory, not lazily.fixAvoid overly broad wildcard patterns in performance-critical applications or when dealing with large numbers of files. Consider a more explicit file inclusion strategy for such scenarios.
affects: All versions
gotchaBy default, `PyYAML`'s `yaml.load()` function can be insecure when dealing with untrusted input due to arbitrary code execution possibilities. Although `pyyaml-include` examples often use `yaml.full_load()`, it's a good practice to be aware.fixAlways use `yaml.safe_load()` for untrusted input or `yaml.full_load()` if you specifically need the features of the `FullLoader` for trusted sources. Register `yaml_include.Constructor` with the appropriate safe loader.
affects: All versions (PyYAML related)
Errors
Common errors & fixes
yaml.constructor.ConstructorError: could not determine a constructor for the tag '!include'
This error occurs because PyYAML encounters the `!include` tag but the `pyyaml-include`'s custom constructor has not been registered to handle it.
fixWhen loading the YAML, explicitly use `yaml_include.YamlIncludeConstructor` as the loader.
ModuleNotFoundError: No module named 'yaml_include'
The `pyyaml-include` package, or its main module `yaml_include`, is not installed in the current Python environment.
fixInstall the package using pip.
ModuleNotFoundError: No module named 's3fs'
When attempting to include a remote file from a service like S3 (e.g., `!include s3://...`), the necessary `fsspec` backend package for that specific protocol (e.g., `s3fs` for S3) is not installed.
fixInstall the required `fsspec` backend package for the specific remote protocol you are using (e.g., `pip install s3fs` for S3, `pip install gcsfs` for Google Cloud Storage).
yaml_include.YamlIncludeException: Included file not found: 'path/to/nonexistent.yaml'
The file path specified within the `!include` tag points to a file that does not exist or is inaccessible from the current working directory or given absolute/relative path.
fixVerify that the path to the included YAML file is correct, the file exists, and the application has the necessary permissions to read it.
Upgrade
Version history
2.2latest on PyPI · released Nov 9, 2024
Audit
Dependencies
PyYAMLrequiredCore dependency, this library extends its functionality.
fsspecoptionalRequired for file system abstraction, enabling local and remote file inclusion (since v2.0). Specific backends like `fsspec[http]` are optional.