Install & Compatibility
Where this runs
tested against v25.3.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.95 runs
installs and imports cleanly · install 0.0s · import 0.322s · 22.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.314s · 24MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
main
✓ from jinjanator.cli import main
Jinjanator is primarily a CLI tool; `main` is its internal entry point. Direct programmatic use of the `jinjanator` *tool* itself is uncommon. For general Python-level templating, import `jinja2` directly.
Environment
✓ from jinja2 import Environment
For programmatic templating within Python applications, you typically interact with the `Jinja2` library directly rather than through `jinjanator`'s internal API.
This quickstart demonstrates how to use `jinjanator` via its command-line interface within a Python script. It creates a temporary Jinja2 template file, sets environment variables, and then executes the `jinjanate` command to render the template. The output is printed to the console.
import subprocess
import os
import tempfile
# Create a simple Jinja2 template content
template_content = "<data><name>{{ name }}</name><age>{{ age }}</age></data>"
# Create a temporary template file
with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix=".j2") as tmp_template:
tmp_template.write(template_content)
template_path = tmp_template.name
try:
# Set environment variables for the subprocess that runs jinjanate
env = os.environ.copy()
env["name"] = "Andrew"
env["age"] = "31"
print(f"Rendering template: {template_path} with name={env['name']}, age={env['age']}")
# Run jinjanate command. Both 'j2' and 'jinjanate' are valid entry points.
result = subprocess.run(
["jinjanate", template_path],
capture_output=True,
text=True,
check=True, # Raise CalledProcessError if the command returns a non-zero exit code
env=env
)
print("\n--- Rendered output ---")
print(result.stdout)
print("-----------------------")
except subprocess.CalledProcessError as e:
print(f"Error rendering template: {e}")
print(f"Stderr: {e.stderr}")
finally:
# Clean up the temporary file
os.remove(template_path)
jinjanator --version
Debug
Known issues
breakingMajor versions of Jinjanator frequently drop support for older Python versions and add support for newer ones. For example, version 25.3.0 removed support for Python 3.9, and 24.4.0 removed Python 3.8 support. Users must ensure their Python environment meets the `requires_python` specification for their installed Jinjanator version.fixUpgrade your Python environment to a version supported by your Jinjanator installation, or pin Jinjanator to an older version that supports your Python environment. Refer to the project's `pyproject.toml` or release notes for current Python compatibility.
affects: 24.4.0, 25.3.0 and newer
breakingThe `jinjanator-plugins` dependency, which underpins extensibility, explicitly recommends pinning to a specific version or a narrow 'year.release' range (e.g., '25.1.*'). This is due to potential non-backward-compatible API changes. Plugins relying on specific `jinjanator-plugins` versions may break if the core `jinjanator` library upgrades its `jinjanator-plugins` dependency or if the plugin itself is not carefully versioned.fixWhen developing or using custom plugins, ensure they explicitly declare and pin their `jinjanator-plugins` dependency to prevent unexpected breakage with `jinjanator` updates. Consult `jinjanator-plugins` documentation for best practices.
affects: All versions that use `jinjanator-plugins`
gotchaIn versions prior to 25.2.0, there was a corrected behavior for the `--customize` argument when the customization file did not contain every possible type of customization function. Users with complex or incomplete customization files on older versions might encounter unexpected behavior.fixUpgrade to Jinjanator 25.2.0 or newer to benefit from the corrected behavior of the `--customize` argument, ensuring all customization functions are handled gracefully, even if not all hooks are present in the file. [cite: 25.2.0 release notes]
affects: <25.2.0
Errors
Common errors & fixes
jinja2.exceptions.TemplateNotFound: <template_name>
The specified Jinja2 template file could not be found by Jinjanator. This often means the file path is incorrect or the file does not exist at the expected location.
fixEnsure the template file exists and that the path provided to the `jinjanate` command is correct, including any relative or absolute paths. For example, if 'my_template.j2' is in the current directory, use `jinjanate my_template.j2`.
UndefinedError: '<variable_name>' is undefined
A variable was referenced in the Jinja2 template but was not provided through any of the specified data sources (INI, YAML, JSON, dotenv files, or environment variables).
fixProvide the missing variable in a data file (e.g., `data.yaml`) and pass it to jinjanator (`jinjanate template.j2 data.yaml`), or set it as an environment variable. Alternatively, use the `--undefined` option with `jinjanate` to allow templates to use undefined variables without raising an error.
jinjanator: command not found
The `jinjanator` command-line tool is either not installed on your system or the directory where it's installed is not included in your system's PATH environment variable.
fixInstall Jinjanator using pip: `pip install jinjanator`. If it's already installed, ensure your system's PATH includes the directory where Python's `bin` or `Scripts` directory (containing the `jinjanate` executable) is located.
jinja2.exceptions.TemplateSyntaxError: Unexpected end of template
The Jinja2 template contains a syntax error where an opening block tag (like `{% if %}` or `{% for %}`) is not properly closed with its corresponding end tag (e.g., `{% endif %}`, `{% endfor %}`).
fixReview your template file for unmatched Jinja2 block tags. Ensure every `{% if %}`, `{% for %}`, etc., has a corresponding `{% endif %}`, `{% endfor %}`. The error message usually indicates the line number where the issue was detected. Upgrade
Version history
25.3.1latest on PyPI · released Dec 24, 2025
Audit
Dependencies
attrsrequiredUtility library for classes without boilerplate.
jinja2requiredThe core templating engine utilized by Jinjanator.
jinjanator-pluginsrequiredAPI package for extending Jinjanator with custom formats, filters, tests, and globals.
python-dotenvrequiredSupport for loading environment variables from .env files.
pyyamlrequiredYAML data format parsing for input files.
typing-extensionsrequiredBackports and extensions for Python's typing module.