Manifest
Pin your dependencies
Manifest dependencies are installed by Ray on the workers; they are not
copied from your local environment. A ranged or unversioned specifier
(numpy, torch>=2.1) therefore resolves to whatever version is newest when
the workers install it, which drifts away from the versions you tested
against locally and surfaces later as serialization errors, missing
attributes, or wrong results.
Pin every dependency to an exact version:
manifest = (
GenevaManifest.create_pip("my-manifest")
.pip(["numpy==2.1.3", "torch==2.10.0", "geneva==0.15.0"])
.build()
)
Building a manifest with unpinned dependencies logs a warning listing the
specifiers to pin. If a range is intentional, call .allow_unpinned() on the
builder to silence it.
A fully pinned requirements.txt (from pip freeze or uv pip compile)
passed via .requirements_path() works equally well. The advisory covers pip
dependencies only; conda manifests are built without it.
A Geneva Manifest represents the files and dependencies used in the execution environment.
created_at: datetime = field(
factory=lambda: now(utc),
metadata={"pa_type": timestamp("us", tz="UTC")},
)
Generate a stable checksum of the manifest, ignoring the checksum field. The zip file names include the checksum of the contents so this hash is comprehensive.
create_pip(name: str) -> PipManifestBuilder
Create a pip-based manifest builder.
Pin dependencies to exact versions: they are installed on the Ray workers, so ranged specifiers can resolve to versions that differ from the local environment.
Examples:
manifest = (
GenevaManifest.create_pip("my-manifest")
.pip(["numpy==2.1.3"])
.build()
)
create_conda(name: str) -> CondaManifestBuilder
Create a conda-based manifest builder.
Pin dependencies to exact versions: they are installed on the Ray workers, so ranged specifiers can resolve to versions that differ from the local environment.
Examples:
manifest = GenevaManifest.create_conda("my-manifest").conda({...}).build()
create_site(name: str) -> SiteManifestBuilder
Create a site-packages manifest builder.
Uploads local site-packages without external dependencies. upload_site_packages defaults to True.
Examples:
manifest = GenevaManifest.create_site("my-manifest").build()
Canonical JSON serialization of this manifest for column metadata storage. Excludes transient/runtime fields.
from_json(payload: str) -> GenevaManifest
Reconstruct a GenevaManifest from a string produced by
to_json.
Missing transient fields fall back to defaults.
Bases: _ManifestBuilderBase
Type-safe builder for pip-based manifests.
This builder does NOT have conda methods - use CondaManifestBuilder for conda.
Pin every dependency to an exact version. Ranged specifiers
(numpy>=2) are resolved when Ray installs them on the workers, so they
can pick up a different version than the local environment and cause
failures that are hard to trace back to the manifest.
Examples:
manifest = (
PipManifestBuilder.create("my-manifest")
.pip(["numpy==2.1.3", "pandas==2.2.3"])
.build()
)
pip(packages: list[str]) -> PipManifestBuilder
Set the runtime pip packages list.
Pin exact versions ("numpy==2.1.3") rather than ranges so workers
install the same versions as the local environment.
Cannot be used with .requirements_path().
add_pip(package: str) -> PipManifestBuilder
Add a single pip package, ideally pinned ("numpy==2.1.3").
requirements_path(path: str) -> PipManifestBuilder
Set the path to a requirements.txt file.
Prefer a fully pinned file, such as one produced by pip freeze or
uv pip compile.
Cannot be used with .pip().
add_extra_index_url(url: str) -> PipManifestBuilder
Add an extra pip index URL for Ray workers.
These URLs are merged with Geneva's default indexes (fury.io) and set in PIP_EXTRA_INDEX_URL for worker processes.
build() -> GenevaManifest
Build the GenevaManifest with pip configuration.
Logs a recommendation when any dependency is not pinned to an exact
version; call .allow_unpinned() to silence it.
create(name: str) -> PipManifestBuilder
Create a new pip manifest builder with the given name.
Set the Python modules for the runtime environment.
Add a single Python module to the runtime environment.
Set the container image for Ray head to the platform default.
Set the container image for Ray workers to the platform default.
Set whether to upload site packages during packaging.
Set whether to delete local zip files after upload.
Set the local directory for zip file output.
Set environment variables for Ray workers via runtime_env.
These override cluster-level env vars for Ray worker processes.
Add a single environment variable for Ray workers.
Silence the recommendation to pin exact dependency versions.
Dependencies are installed on the Ray workers at run time, so ranged or unversioned specifiers may resolve to versions that differ from the local environment. Use this only when that drift is intended.
Bases: _ManifestBuilderBase
Type-safe builder for conda-based manifests.
This builder does NOT have pip methods - use PipManifestBuilder for pip.
Pin every dependency to an exact version. Ranged specifiers
(numpy>=2) are resolved when Ray creates the environment on the
workers, so they can pick up a different version than the local
environment and cause failures that are hard to trace back to the
manifest.
Examples:
manifest = (
CondaManifestBuilder.create("my-manifest")
.conda({"dependencies": ["python=3.10.14", "numpy=2.1.3"]})
.build()
)
conda(dependencies: dict[str, Any]) -> CondaManifestBuilder
Set the conda dependencies for the runtime environment.
Pin exact versions ("numpy=2.1.3") rather than ranges so workers
install the same versions as the local environment.
Cannot be used with .conda_environment_path().
conda_environment_path(path: str) -> CondaManifestBuilder
Set the path to a conda environment.yml file.
Prefer a fully pinned file, such as one produced by
conda env export.
Cannot be used with .conda().
build() -> GenevaManifest
Build the GenevaManifest with conda configuration.
Logs a recommendation when any dependency is not pinned to an exact
version; call .allow_unpinned() to silence it.
create(name: str) -> CondaManifestBuilder
Create a new conda manifest builder with the given name.
Set the Python modules for the runtime environment.
Add a single Python module to the runtime environment.
Set the container image for Ray head to the platform default.
Set the container image for Ray workers to the platform default.
Set whether to upload site packages during packaging.
Set whether to delete local zip files after upload.
Set the local directory for zip file output.
Set environment variables for Ray workers via runtime_env.
These override cluster-level env vars for Ray worker processes.
Add a single environment variable for Ray workers.
Silence the recommendation to pin exact dependency versions.
Dependencies are installed on the Ray workers at run time, so ranged or unversioned specifiers may resolve to versions that differ from the local environment. Use this only when that drift is intended.
Bases: _ManifestBuilderBase
Type-safe builder for site-packages manifests.
This builder uploads local site-packages without external dependencies. It does NOT have pip or conda methods.
upload_site_packages defaults to True for this builder.
Examples:
manifest = SiteManifestBuilder.create("my-manifest").build()
create(name: str) -> SiteManifestBuilder
Create a new site manifest builder with the given name.
Set the Python modules for the runtime environment.
Add a single Python module to the runtime environment.
Set the container image for Ray head to the platform default.
Set the container image for Ray workers to the platform default.
Set whether to upload site packages during packaging.
Set whether to delete local zip files after upload.
Set the local directory for zip file output.
Set environment variables for Ray workers via runtime_env.
These override cluster-level env vars for Ray worker processes.
Add a single environment variable for Ray workers.
Silence the recommendation to pin exact dependency versions.
Dependencies are installed on the Ray workers at run time, so ranged or unversioned specifiers may resolve to versions that differ from the local environment. Use this only when that drift is intended.