Edit

Customize a base image for compute session

Warning

Prompt flow in Microsoft Foundry and Azure Machine Learning will be retired on April 20, 2027. Prompt flow is no longer recommended for new development. Migrate existing Prompt flow applications and deployments to Microsoft Agent Framework before April 20, 2027.

Prompt flow container images are no longer receiving updates, including security and package updates. This applies to Prompt flow runtime images, including promptflow-runtime, promptflow-runtime-stable, and promptflow-python.

After April 20, 2027, Prompt flow, including the web authoring experience in Microsoft Foundry and Azure Machine Learning, the VS Code extensions, and related Prompt flow container images, will no longer be supported or available.

If your application depends on Prompt flow deployments or runtime images, plan to move those workloads to supported alternatives such as Microsoft Agent Framework before the retirement date. For migration guidance, see the Prompt flow migration guide and migration code samples.

Before you begin, make sure you're familiar with Docker and Azure Machine Learning environments.

Step 1: Prepare the Docker context

Create image_build folder

In your local environment, create a folder that contains the following files. The folder structure should look like this:

|--image_build
|  |--requirements.txt
|  |--Dockerfile
|  |--environment.yaml

Define your required packages in requirements.txt

Optional: Add packages in private PyPI repository.

Use the following command to download your packages locally: pip wheel <package_name> --index-url=<private pypi> --wheel-dir <local path to save packages>

Open the requirements.txt file and add your extra packages and their specific versions. For example:

###### Requirements with Version Specifiers ######
numpy == 2.2.0              # Version Matching. Must be version 2.2.0
requests >= 2.31.0          # Minimum version 2.31.0
coverage != 3.5             # Version Exclusion. Anything except version 3.5
pydantic ~= 2.0             # Compatible release. Same as >= 2.0, == 2.*
<path_to_local_package>     # reference to local pip wheel package

For more information about structuring the requirements.txt file, see Requirements file format in the pip documentation.

Define the Dockerfile

Create a Dockerfile and add the following content, then save the file:

FROM <Base_image>
COPY ./* ./
RUN pip install -r requirements.txt

Note

Build this Docker image from the prompt flow base image mcr.microsoft.com/azureml/promptflow/promptflow-runtime:<newest_version>. If possible, use the latest version of the base image.

Step 2: Create custom Azure Machine Learning environment

Define your environment in environment.yaml

On your local computer, use the CLI (v2) to create a customized environment based on your Docker image.

Note

az login # if not already authenticated

az account set --subscription <subscription ID>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

Open the environment.yaml file and add the following content. Replace the <environment_name> placeholder with your desired environment name.

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: <environment_name>
build:
  path: .

Create an environment

cd image_build
az ml environment create -f environment.yaml --subscription <sub-id> -g <resource-group> -w <workspace>

Note

Building the environment image might take several minutes.

Go to your workspace UI page, then go to the environment page, and locate the custom environment you created.

You can also find the image in the environment detail page and use it as base image for compute session of prompt flow. This image is also used to build environment for flow deployment from UI. To learn more, see how to specify base image in compute session.

To learn more about environment CLI, see Manage environments.

Next steps

  • Last updated on