Install & Compatibility
Where this runs
tested against v0.1.50 · 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.940 runs
installs and imports cleanly · install 0.0s · import 0.503s · 77.3MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 4.9s · import 0.461s · 77MB
77MB installed
● package 77MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
prompty
✓ import prompty
✗ from prompty import prompty
This quickstart demonstrates how to create a `.prompty` file and execute it using the `prompty.execute` function for a one-shot operation, or `prompty.load`, `prompty.prepare`, and `prompty.run` for a step-by-step pipeline. It uses an OpenAI model and requires the `OPENAI_API_KEY` environment variable to be set.
import os
import prompty
# Create a dummy .prompty file for the example
prompty_content = """
---
name: greeting
model:
id: gpt-4o-mini
provider: openai
connection:
kind: key
apiKey: ${env:OPENAI_API_KEY}
inputSchema:
properties:
name:
kind: string
default: World
template:
format:
kind: jinja2
parser:
kind: prompty
---
system: You are a friendly assistant.
user: Say hello to {{name}}.
"""
with open("greeting.prompty", "w") as f:
f.write(prompty_content)
# Ensure OPENAI_API_KEY is set in your environment
# For local testing, you might set it like this:
# os.environ["OPENAI_API_KEY"] = "your_openai_api_key_here"
openai_api_key = os.environ.get('OPENAI_API_KEY', '')
if not openai_api_key:
print("Warning: OPENAI_API_KEY environment variable not set. Skipping execution.")
print("Please set OPENAI_API_KEY for the quickstart to run successfully.")
else:
try:
# One-shot: load + prepare + run
result = prompty.execute(
"greeting.prompty",
inputs={"name": "Jane"}
)
print("\nPrompty execution result (one-shot):")
print(result)
# Step-by-step example
agent = prompty.load("greeting.prompty")
messages = prompty.prepare(
agent,
inputs={"name": "World"}
)
step_by_step_result = prompty.run(agent, messages)
print("\nPrompty execution result (step-by-step):")
print(step_by_step_result)
except Exception as e:
print(f"\nAn error occurred during Prompty execution: {e}")
print("Ensure your OPENAI_API_KEY is valid and has access to gpt-4o-mini.")
# Clean up the dummy file
os.remove("greeting.prompty")
Debug
Known issues
breakingThe Prompty specification evolved from v1 to v2, introducing changes in metadata structure. For example, `model.configuration` became `model.connection`, `model.parameters` became `model.options`, and `inputs` moved to `inputSchema.properties`. While Prompty v2 aims for backward compatibility by migrating v1 files, be aware of these structural changes when working with older `.prompty` assets.fixReview and update older `.prompty` files to align with the v2 specification, or ensure your runtime correctly handles the automatic migration (which may issue deprecation warnings). Refer to the official Prompty specification for the latest format details.
affects: All versions running Prompty v2 spec against v1 files.
gotchaPrompty relies on specific 'extra' installations for different LLM providers (e.g., `[openai]` for OpenAI, `[azure]` for Azure OpenAI) and template engines (e.g., `[jinja2]`). Forgetting to install these can lead to `ImportError` or `ModuleNotFoundError` at runtime when trying to use a particular provider or templating feature.fixAlways install `prompty` with the necessary extras, for example: `pip install prompty[openai,jinja2]` or `pip install prompty[all]` for all features.
affects: All versions.
gotchaPrompty files frequently use environment variables (e.g., `${env:OPENAI_API_KEY}`, `${env:AZURE_OPENAI_ENDPOINT}`) for model connection and API keys. If these environment variables are not correctly set in the execution environment, the Prompty runtime will fail to authenticate or connect to the LLM, leading to runtime errors.fixEnsure all required environment variables specified in your `.prompty` files are properly set in the shell or application environment before execution. Consider using `python-dotenv` for local development.
affects: All versions.
gotchaWhile PyPI states `requires_python>=3.9`, the official documentation and code guidelines often recommend Python 3.10 or higher (and sometimes specifically 3.11 for modern syntax). Using Python 3.9 might limit access to newer features or cause unexpected behavior with examples written for later Python versions.fixPreferably use Python 3.10 or a newer version (e.g., 3.11+) to ensure full compatibility with the latest Prompty documentation and features. Check the Prompty GitHub repository's `RELEASING.md` for current test matrix details.
affects: <=0.1.50 (Python 3.9 users)
gotchaPrompty is designed with a strong integration with a VS Code extension for authoring, debugging, and testing `.prompty` files. While the Python runtime can execute `.prompty` files independently, relying solely on the runtime without the VS Code extension can make the initial prompt engineering and debugging process less efficient for some users.fixFor an optimized prompt engineering workflow, consider installing the Prompty VS Code extension alongside the Python runtime. This provides a rich IDE experience with features like syntax highlighting, live preview, and integrated tracing.
affects: All versions.
Upgrade
Version history
0.1.50latest on PyPI · released Apr 2, 2025
Audit
Dependencies
python>=3.9requiredMinimum Python version required by PyPI. Newer documentation often recommends Python 3.10+ or 3.11+ for full compatibility with examples and modern features.
openaioptionalRequired for OpenAI provider support (installed via `prompty[openai]`).
azure-identityoptionalRequired for Microsoft Foundry provider support (installed via `prompty[foundry]`).
jinja2optionalRequired for Jinja2 template rendering (installed via `prompty[jinja2]`).