Install & Compatibility
Where this runs
tested against v2026.1.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
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.000s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
StarlarkError
✓ from starlark import StarlarkError
✗ from starlark_pyo3 import Starlark
Module
✓ from starlark import Module
eval
✓ from starlark import eval
This quickstart demonstrates how to initialize the Starlark interpreter, define a load function for importing other Starlark files, evaluate a Starlark script, and access global variables and functions from the evaluated context. It also shows how to pass Python objects as globals into the Starlark environment.
from starlark_pyo3 import Starlark, init_once
import os
# Initialize the Starlark interpreter (safe to call multiple times)
init_once()
# Define a simple Starlark script
starlark_script = '''
load('foo.star', 'my_func')
def greet(name):
return f"Hello, {name}!"
my_value = greet("Starlark")
'''
# Define a load function for external Starlark files
def load_func(name):
if name == 'foo.star':
return "def my_func(x): return x * 2"
raise ValueError(f"Unknown module: {name}")
# Create a Starlark instance with custom globals and a load function
starlark_interpreter = Starlark(globals={'MAGIC_NUMBER': 42}, load_func=load_func)
# Evaluate the script
result_globals = starlark_interpreter.eval(starlark_script)
# Access a variable from the evaluated script
print(f"Result from Starlark: {result_globals['my_value']}")
# Call a function directly from the evaluated module
print(f"Calling greet: {result_globals['greet']('World')}")
# Verify a global was passed
print(f"Magic number: {result_globals['MAGIC_NUMBER']}")
# Evaluate an expression directly
expression_result = starlark_interpreter.eval('10 * MAGIC_NUMBER')
print(f"Expression result: {expression_result}")
Debug
Known issues
breakingMajor version upgrades of `pyo3` and `starlark-rust` can introduce breaking changes in API behavior or underlying data structures, especially if you're interacting with lower-level components or custom extensions. Always review the release notes carefully.fixThoroughly test your application after upgrading. Consult the changelog for `starlark-pyo3` and the upstream `starlark-rust` and `pyo3` libraries for specific API changes. Re-evaluate any custom Python objects passed into Starlark.
affects: v2025.2, v2025.1, v2024.1.5 (and potentially others)
gotchaThe `init_once()` function must be called to initialize the underlying Rust Starlark interpreter. While it's safe to call multiple times, forgetting it will lead to errors.fixEnsure `from starlark_pyo3 import init_once` and `init_once()` are present in your application's bootstrap code, typically before any `Starlark` instances are created or `eval` operations are performed.
affects: All versions
gotchaChanges to Starlark's type system or evaluation rules (e.g., `typecheck` introduction, handling of Python objects) might subtly alter script behavior or introduce new errors.fixReview release notes for changes related to type checking and Python object handling. Validate existing Starlark scripts against new versions, paying attention to type coercion and object visibility.
affects: v2025.2, v2025.2.5
gotchaThe `FrozenModule.call` method gained `kwargs` support in `v2025.2.3`. If you previously had workarounds for passing keyword arguments or expected specific behavior, this change might impact your code.fixUpdate your code to leverage the direct `kwargs` support when calling Starlark functions from Python. Remove any manual workarounds for keyword arguments.
affects: Prior to v2025.2.3
Upgrade
Version history
2026.1.1latest on PyPI · released Aug 23, 2026
Audit
Dependencies
No dependency data recorded yet.