modal.Secret

class Secret(modal.object.Object)

Secrets provide a dictionary of environment variables for images.

Secrets are a secure way to add credentials and other sensitive information to the containers your functions run in. You can create and edit secrets on the dashboard, or programmatically from Python code.

See the secrets guide page for more information.

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.

objects

objects: SecretManager

Namespace with methods for managing named Secret objects.

objects.create

create(self, name, env_dict, *, allow_existing=False, environment_name=None,
    client=None)

Create a new named Secret in the workspace environment.

This does not return a local handle; use modal.Secret.from_name to look up the Secret after creation.

Added in v1.1.2.

Parameters

name str

Name for the new Secret.

env_dict dict[str, str]

Environment variable keys and values stored in the Secret.

allow_existing bool

If True, do nothing when a Secret with this name already exists (existing values are kept). (Default is False)

environment_name str | None

Environment to create in; defaults to the active environment.

client _Client | None

Modal client to use; defaults to Client.from_env() when omitted.

Usage

contents = {"MY_KEY": "my-value", "MY_OTHER_KEY": "my-other-value"}
modal.Secret.objects.create("my-secret", contents)

Secrets will be created in the active environment, or another one can be specified:

modal.Secret.objects.create("my-secret", contents, environment_name="dev")

By default, an error will be raised if the Secret already exists, but passing allow_existing=True will make the creation attempt a no-op in this case. If the env_dict data differs from the existing Secret, it will be ignored.

modal.Secret.objects.create("my-secret", contents, allow_existing=True)

Note that this method does not return a local instance of the Secret. You can use modal.Secret.from_name to perform a lookup after creation.

objects.list

list(self, *, max_objects=None, created_before=None, environment_name="",
    client=None)

List named Secrets in the workspace environment as hydrated handles.

Results are ordered newest to oldest. By default, all matching Secrets are returned.

Added in v1.1.2.

Parameters

max_objects int | None

Maximum number of Secrets to return.

created_before datetime | str | None

Only include Secrets created before this time (datetime or ISO date string).

environment_name str

Environment to list from; defaults to the active environment. (Default is "")

client _Client | None

Modal client to use; defaults to Client.from_env() when omitted.

Returns

Hydrated Secret objects for each named Secret in the listing.

Usage

secrets = modal.Secret.objects.list()
print([s.name for s in secrets])

Secrets will be retrieved from the active environment, or another one can be specified:

dev_secrets = modal.Secret.objects.list(environment_name="dev")

By default, all named Secrets are returned, newest to oldest. It’s also possible to limit the number of results and to filter by creation date:

secrets = modal.Secret.objects.list(max_objects=10, created_before="2025-01-01")

objects.delete

delete(self, name, *, allow_missing=False, environment_name=None, client=None)

Delete a named Secret entirely.

Deletion is irreversible and affects any Apps using this Secret.

Added in v1.1.2.

Parameters

name str

Name of the Secret to delete.

allow_missing bool

If True, do nothing when the Secret does not exist. (Default is False)

environment_name str | None

Environment to delete from; defaults to the active environment.

client _Client | None

Modal client to use; defaults to Client.from_env() when omitted.

Usage

await modal.Secret.objects.delete("my-secret")

Secrets will be deleted from the active environment, or another one can be specified:

await modal.Secret.objects.delete("my-secret", environment_name="dev")

name

name(self)

from_dict

from_dict(env_dict={})

Create a Secret from a dictionary of environment variable names to string values.

Values may be None; those keys are omitted from the Secret.

Parameters

env_dict dict[str, str | None]

Mapping of variable names to values (or None to skip a key). (Default is {})

Returns

A lazy Secret handle backed by the given key-value pairs.

Usage

@app.function(secrets=[modal.Secret.from_dict({"FOO": "bar"})])
def run():
    print(os.environ["FOO"])

from_local_environ

from_local_environ(env_keys)

Build a Secret from the current process environment (local runs only).

In remote execution, returns an empty Secret.

Parameters

env_keys list[str]

Names of environment variables to copy into the Secret.

Returns

A Secret containing the resolved variables (or empty when not local).

from_dotenv

from_dotenv(path=None, *, filename=".env", client=None)

Load environment variables from a .env file into a Secret.

With no path, searches from the current working directory (not the caller’s file path). With path set, walks upward from that file or directory to find filename.

Parameters

path

File or directory to search from; omit to search from the process cwd.

filename

Name of the env file to find (default .env). (Default is ".env")

client _Client | None

Modal client used when hydrating the Secret.

Returns

A lazy Secret handle whose values are loaded from the resolved .env file.

Usage

@app.function(secrets=[modal.Secret.from_dotenv(__file__)])
def run():
    print(os.environ["USERNAME"])  # Assumes USERNAME is defined in your .env file

@app.function(secrets=[modal.Secret.from_dotenv(filename=".env-dev")])
def run():
    ...

from_name

from_name(name, *, environment_name=None, required_keys=[], client=None)

Reference a deployed Secret by name.

Hydration is lazy until the Secret is used.

Parameters

name str

Deployment name of the Secret.

environment_name str | None

Environment to resolve the name in; defaults to the active environment.

required_keys list[str]

If non-empty, the server asserts these keys exist on the Secret. (Default is [])

client _Client | None

Modal client to use for loading; defaults to Client.from_env() when omitted.

Returns

A Secret handle (possibly not yet hydrated).

Usage

secret = modal.Secret.from_name("my-secret")

@app.function(secrets=[secret])
def run():
    ...

info

info(self)

Return information about the Secret object.

update

update(self, env_dict)

Update this Secret, adding or overwriting key-value pairs.

Like dict.update(), this merges env_dict into the existing Secret. Keys not mentioned in env_dict are left unchanged.