Environment

class Environment(modal.object.Object)

hydrate

hydrate(self, client=None)

Synchronize the local object with its identity on the Modal server.

It is rarely necessary to call this method explicitly, as most operations will lazily hydrate when needed. The main use case is when you need to access object metadata, such as its ID.

Added in v0.72.39: This method replaces the deprecated .resolve() method.

name

name(self)

objects

objects: EnvironmentManager

Namespace with methods for managing Environment objects.

objects.create

create(self, name, *, restricted=False, default_role=None,
    experimental_options=None, client=None)

Create a new Environment.

Examples:

modal.Environment.objects.create("my-environment")

objects.list

list(self, *, client=None)

Return a list of hydrated Environment objects.

Examples:

environments = modal.Environment.objects.list()
print([e.name for e in environments])

objects.delete

delete(self, name, *, client=None)

Delete a named Environment.

Warning: This is irreversible and will transitively delete all objects in the Environment.

Examples:

modal.Environment.objects.delete("my-environment")

roles

roles: EnvironmentRolesManager

Namespace with methods for managing the Environment Roles of users and service users.

See https://modal.com/docs/guide/rbac for more information on Environment Roles.

roles.list

list(self, *, exclude_default=False)

Enumerate the Environment Role for each user and service user in the workspace.

Examples:

roles = modal.Environment.from_name("my-env").roles.list()
print(roles)
# {
#     "users": {"alice": "contributor", "bob": "viewer", "carol": "contributor"},
#     "service_users": {"alice-bot": "contributor", "ops-bot": "viewer", "ci-bot": "no-access"},
# }

Parameters

roles.update

update(self, *, users=None, service_users=None)

Update the Environment Role of users and service users.

Each role is one of 'contributor', 'viewer', or 'no-access'. Service users can be assigned a role on any Environment, while workspace members can only be assigned a role on restricted Environments.

Examples:

env = modal.Environment.from_name("my-restricted-env")
env.roles.update(
    users={"alice": "contributor", "bob": "viewer"},
    service_users={"alice-bot": "contributor"},
)

from_context

from_context(*, client=None)

Look up an Environment object using the current context.

This method returns the Environment that is defined by the local configuration (i.e., your active profile or the MODAL_ENVIRONMENT environment variable), or it fetches the default environment from the server when not defined locally. If called inside a Modal container, it will return the Environment that container is associated with.

from_name

from_name(name, *, create_if_missing=False, client=None)

Look up an Environment object using its name.

billing

billing: EnvironmentBillingManager

Namespace for Environment billing APIs.

__init__(self, environment)

mdmd:ignore

billing.report

report(self, *, start, end=None, resolution="d", tag_names=None)

Return a cost report for Environment usage, broken down by object and time.

Parameters

Returns

A list of BillingReportItem dataclasses. Each item reports the cost attributed to a specific Modal object during a given time interval. Cost is further broken down by the resource type that generated it (e.g. CPU, Memory, specific GPU usage). Note that the specific resource types included in the breakdown are subject to change as Modal's billing model evolves.

See Also

• modal environment billing report: An environment report CLI that has convenience features around relative time range queries and JSON/CSV output.
• Workspace.billing.report(): An analogous report API for the entire Workspace.

billing.summary

summary(self, cycle=None)

Return a summary of environment cost over a single billing cycle determined by cycle.

Unlike the analogous Workspace.billing.summary(), this API only emits metered cost information. This is because billing adjustments due to credits, free storage, etc. are applied at the Workspace level, and thus cannot be attributed to individual Environments.

Parameters

Returns

A single EnvironmentBillingSummary dataclass containing the following fields:

• metered_cost representing cost before any adjustments, and
• metered_cost_breakdown containing a breakdown of that cost by the Modal resources that generated it. The exact keys of this are subject to change as Modal's billing model evolves.

All values are reported as decimal.Decimals.

See Also

• modal environment billing summary: An environment summary CLI that has convenience features around relative time range queries.
• Environment.billing.report(): An analogous report API that is scoped to a specific Environment.