---
id: pyyaml-include
version: "2.2"
license: GPLv3+
license_treatment: copyleft
maintenance: active
---

# pyyaml-include — An extending constructor of PyYAML: include other YAML files into current YAML document

License: copyleft · Maintenance: active · Downloads: 5.3M/mo

## What it is and what it does

pyyaml-include is an extension to PyYAML that lets you split YAML configuration across multiple files and include them into a single document at parse time. Instead of managing one monolithic YAML file, you register a custom constructor that tells PyYAML to load and merge external files wherever you place the include tag. It works with local files, shell-style wildcards (*, ?, **), and remote sources like HTTP, S3, and SFTP via fsspec.

The package is useful for large configuration systems where you want to organize settings by component or environment. You can include files in mappings (as key-value pairs) or sequences (as list items), and the included YAML is parsed and merged into the document tree. Version 2.0 introduced fsspec support, making it possible to include files from cloud storage or web servers without manual downloads.

Use it for:

- Organize application configuration across multiple YAML files by feature or environment, then include them all in a main config file.
- Load configuration fragments from a remote HTTP server or S3 bucket at runtime without manual downloads.
- Use wildcards to automatically include all YAML files matching a pattern from a directory.
- Build layered configuration systems where base settings are in one file and environment-specific overrides are included conditionally.
- Modularize Kubernetes manifests or Docker Compose definitions by splitting them into separate files and including them in a root manifest.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Extends PyYAML to include other YAML files into a current YAML document, with support for local files, wildcards, and remote sources via fsspec (HTTP, S3, SFTP, etc.).

Yes, with conditions. Install if you need to split YAML configuration across files and want a lightweight, actively maintained solution. The low install friction and broad Python support make it straightforward to adopt. However, the GPLv3+ copyleft license restricts use in proprietary closed-source projects—verify license compatibility before committing. No known security vulnerabilities.

## Install

pip install pyyaml-include
uv add pyyaml-include
poetry add pyyaml-include

## Installing pyyaml-include

Before you install: Low friction: pure Python wheel with three straightforward dependencies (PyYAML, fsspec, typing-extensions). Active maintenance with recent commits; repository shows ongoing development. Supports Python 3.8 through 3.13.

License in practice: GPLv3+ copyleft license: you must license any derivative work under GPLv3 or later if you distribute it. Acceptable for internal use and open-source projects compatible with GPL, but restrictive for proprietary software.

Quickstart:

pip install pyyaml-include

# In your Python code, register a constructor and load YAML
with open('config.yml') as f:
    data = yaml.full_load(f)

Requires PyYAML; for remote file access (HTTP, S3, SFTP), additional fsspec extras must be installed (e.g., fsspec[http], fsspec[s3]).

Verify before relying:

- Performance characteristics when including many large files or using wildcards on large directory trees.
- Memory consumption patterns with deeply nested or recursive includes.
- Compatibility with all fsspec backends beyond HTTP, S3, and SFTP.

## Package facts

- License: GPLv3+ (copyleft)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 5.3M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

yaml file inclusion, include yaml files, yaml composition, yaml external references, multi-file yaml loading, yaml templating, remote yaml includes, yaml-composition, config-management, fsspec-integration

[View on SkillFed](https://skillfed.io/packages/pyyaml-include) · [View on PyPI](https://pypi.org/project/pyyaml-include/)