Install & Compatibility
Where this runs
tested against v3.11.0 · 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.412s · 31.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.6s · import 0.376s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
EvgTask
✓ from shrub.v3.evg_task import EvgTask
✗ from shrub.evg_task import EvgTask
The library's API is versioned under the `shrub.vX` namespace. Always import from the specific major version (e.g., `v3`) to ensure compatibility with the desired Evergreen API version.
ShrubService
✓ from shrub.v3.shrub_service import ShrubService
✗ from shrub.shrub_service import ShrubService
Similar to other components, `ShrubService` is part of the versioned API. Ensure you import from the correct `vX` namespace.
This quickstart demonstrates how to define an Evergreen project configuration using shrub.py. It creates multiple parallel tasks, groups them under a display task, associates them with a build variant, and then generates the corresponding Evergreen JSON output. This example illustrates task definition, command execution with variables, and task dependencies.
from shrub.v3.evg_task import EvgTask, EvgTaskDependency
from shrub.v3.evg_build_variant import BuildVariant, DisplayTask
from shrub.v3.evg_command import FunctionCall
from shrub.v3.evg_project import EvgProject
from shrub.v3.shrub_service import ShrubService
import json
n_tasks = 3
def define_task(index):
name = f"my_test_task_{index}"
return EvgTask(
name=name,
commands=[
FunctionCall(func="do_setup_function"),
FunctionCall(
func="run_test_script",
vars={
"param1": f"value_{index}",
"param2": "static_value"
}
),
FunctionCall(func="do_teardown_function")
],
depends_on=[EvgTaskDependency(name="compile_job")]
)
tasks = [define_task(i) for i in range(n_tasks)]
display_task = DisplayTask(
name="full_test_suite",
execution_tasks=[t.name for t in tasks]
)
variant = BuildVariant(
name="linux-build",
tasks=[],
display_tasks=[display_task]
)
project = EvgProject(buildvariants=[variant], tasks=tasks)
# Generate the Evergreen JSON configuration
evergreen_config_json = ShrubService.generate_json(project)
print(json.dumps(evergreen_config_json, indent=4))
Debug
Known issues
breakingShrub.py uses versioned import paths (e.g., `shrub.v3`). Upgrading to a new major version of the library may require updating import statements to reflect the new API version (e.g., from `shrub.v2` to `shrub.v3`).fixReview the official `shrub.py` documentation and release notes for breaking changes and update import paths (e.g., `from shrub.v2...` to `from shrub.v3...`) and object constructors accordingly.
affects: <3.0.0 (hypothetical, as `v3` is current)
gotchaThe structure and available fields for Evergreen configurations are dictated by the Evergreen API itself. Errors in generated JSON often stem from mismatches with the expected Evergreen schema, rather than `shrub.py` library issues.fixAlways consult the official Evergreen documentation for the precise structure and valid values for project configurations, tasks, and commands when encountering issues with the generated JSON.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'shrub.py'
The Python package `shrub-py` is installed, but the main module to import is `shrub` (or `shrub.v2`), not `shrub.py` as a direct module.
fixUse `import shrub` or `from shrub.v2 import Configuration` (or other components) to import the library correctly.
TypeError: __init__() missing 1 required positional argument: 'name'
When creating `BuildVariant`, `Task`, `TaskGroup`, or other core Shrub.py objects, the `name` argument is mandatory and was omitted in the constructor call.
fixProvide a string value for the `name` argument, e.g., `BuildVariant(name="my_variant")` or `Task("my_task_name")`. AttributeError: 'Configuration' object has no attribute 'add_variant'
The `Configuration` object in `shrub.v2` uses the method `add_build_variant` (plural `variants`) to add build variants, not `add_variant`.
fixUse `config.add_build_variant(my_build_variant_object)` to add a build variant to the configuration.
TypeError: FunctionCall() takes 2 positional arguments but 3 were given
The `FunctionCall` constructor expects a function name (string) and a dictionary of arguments, but an incorrect number or type of arguments (e.g., a non-dictionary for arguments) was provided.
fixEnsure `FunctionCall` (and similar command objects) is called with the correct signature, for example: `FunctionCall('my_function', {'param1': 'value1', 'param2': 123})`. Upgrade
Version history
3.11.0latest on PyPI · released Jun 4, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.8.1 or newer.