Set and get variables

Prefect variables are dynamically-named, mutable string values.

Variables enable you to store and reuse non-sensitive bits of data, such as configuration information. They are:

• named, mutable values of any JSON type
• scoped to a self-hosted Prefect server instance or a single workspace in a Prefect Cloud account
• meant for values with infrequent writes and frequent reads (but you can create or modify variables at any time)
• cacheable for quicker retrieval
• most commonly loaded during flow runtime (but you can load them in other contexts to pass configuration information to Prefect configuration files, such as deployment steps)

Variables are not Encrypted

We do not recommend using variables to store sensitive information. Instead, use Secret blocks to store and access sensitive information.

Manage variables

Create, read, edit, and delete variables through the Prefect UI, API, and CLI. Names must adhere to these traditional variable naming conventions:

• Have no more than 255 characters
• Only contain lowercase alphanumeric characters ([a-z], [0-9]) or underscores (_). Spaces are not allowed.
• Be unique

Values must have less than or equal to 5000 characters.

Optionally, you can add tags to a variable.

Through the Prefect UI

View all the variables in your self-hosted Prefect server instance or Prefect Cloud account workspace in the Variables page of the Prefect UI. Both the name and value of all variables are visible to anyone with access to the server or workspace.

To create a new variable:

1. Select the + button next to the header of the Variables page.
2. Enter the name and value of the variable.

Through the REST API

You can create and delete variables through the REST API. You can also set and get variables through the API with either the variable name or ID.

See the REST reference for more information.

Through the CLI

• prefect variable set creates or updates a variable.
• prefect variable get retrieves a variable’s value.
• prefect variable unset deletes a variable.
• prefect variable ls lists all variables.
• prefect variable inspect shows a variable’s details.

Access variables

In addition to the UI and API, you can reference variables in code and in certain Prefect configuration files.

In Python code

You can interact with variables through the Python SDK using the get, set, and unset methods.

from prefect.variables import Variable

assert Variable.set("answer", 42) == Variable(name="answer", value=42, tags=[])

assert Variable.get("answer") == 42

assert Variable.set("answer", 9001, overwrite=True) == Variable(name="answer", value=9001, tags=[])

assert Variable.unset("answer") is True

assert Variable.get("answer", "fallback") == "fallback"

You can use overwrite=True to update the value of an existing variable.

Contextual Behavior

In a sync context (such as an if __name__ == "__main__" block or simple def scope), these methods are used synchronously. In an async context (such as an async def scope), they are used asynchronously.

In prefect.yaml deployment steps

In .yaml files, variables are expressed as strings wrapped in quotes and double curly brackets:

"{{ prefect.variables.my_variable }}"

Use variables to templatize deployment steps by referencing them in the prefect.yaml file that creates the deployments.

For example, you can pass in a variable to specify a branch for a git repo in a deployment pull step:

pull:
- prefect.deployments.steps.git_clone:
    repository: https://github.com/PrefectHQ/hello-projects.git
    branch: "{{ prefect.variables.deployment_branch }}"

The deployment_branch variable is evaluated at runtime for the deployed flow, allowing changes to variables used in a pull action without updating a deployment directly.