# PythonAppResourceBuilderExtensions Methods

- Package: [Aspire.Hosting.Python](/reference/api/csharp/aspire.hosting.python.md)
- Type: [PythonAppResourceBuilderExtensions](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions.md)
- Kind: `Methods`
- Members: `11`

Provides extension methods for adding Python applications to an `Hosting.IDistributedApplicationBuilder`.

## AddPythonApp(IDistributedApplicationBuilder, string, string, string)

- Name: `AddPythonApp(IDistributedApplicationBuilder, string, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PythonAppResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/a3766e994fd2cba86c8ac60b8a80268cab7e6383/src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs#L70-L71)

Adds a Python application to the application model.

```csharp
public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<PythonAppResource> AddPythonApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string scriptPath)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IDistributedApplicationBuilder`)
  The `Hosting.IDistributedApplicationBuilder` to add the resource to.
- `name` (`string`)
  The name of the resource.
- `appDirectory` (`string`)
  The path to the directory containing the python application.
- `scriptPath` (`string`)
  The path to the script relative to the app directory to run.

## Returns

`IResourceBuilder<PythonAppResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method executes a Python script directly using `python script.py`. By default, the virtual environment is resolved using the following priority:

1. If `.venv` exists in the app directory, use it.
2. If `.venv` exists in the AppHost directory, use it.
3. Otherwise, default to `.venv` in the app directory.

Use [PythonAppResourceBuilderExtensions.WithVirtualEnvironment(IResourceBuilder<T>, string, bool)](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods.md#withvirtualenvironment-iresourcebuilder-t-string-bool) to specify a different virtual environment path. Use `WithArgs` to pass arguments to the script.

Python applications automatically have debugging support enabled.

## Examples

Add a FastAPI Python application to the application model:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddPythonApp("fastapi-app", "../api", "main.py")
       .WithArgs("arg1", "arg2");

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## AddPythonApp(IDistributedApplicationBuilder, string, string, string, string[])

> **Obsolete:** Use AddPythonScript, AddPythonModule, or AddPythonExecutable and chain with .WithArgs(...) instead.

- Name: `AddPythonApp(IDistributedApplicationBuilder, string, string, string, string[])`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PythonAppResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/a3766e994fd2cba86c8ac60b8a80268cab7e6383/src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs#L184-L188)

Adds a python application with a virtual environment to the application model.

```csharp
public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<PythonAppResource> AddPythonApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string scriptPath,
        params string[] scriptArgs)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IDistributedApplicationBuilder`)
  The `Hosting.IDistributedApplicationBuilder` to add the resource to.
- `name` (`string`)
  The name of the resource.
- `appDirectory` (`string`)
  The path to the directory containing the python app files.
- `scriptPath` (`string`)
  The path to the script relative to the app directory to run.
- `scriptArgs` (`string[]`)
  The arguments for the script.

## Returns

`IResourceBuilder<PythonAppResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Remarks

This overload is obsolete. Use one of the more specific methods instead:

- [PythonAppResourceBuilderExtensions.AddPythonApp(IDistributedApplicationBuilder, string, string, string)](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods.md#addpythonapp-idistributedapplicationbuilder-string-string-string) - To run a Python script file
- [PythonAppResourceBuilderExtensions.AddPythonModule(IDistributedApplicationBuilder, string, string, string)](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods.md#addpythonmodule-idistributedapplicationbuilder-string-string-string) - To run a Python module via `python -m`
- [PythonAppResourceBuilderExtensions.AddPythonExecutable(IDistributedApplicationBuilder, string, string, string)](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods.md#addpythonexecutable-idistributedapplicationbuilder-string-string-string) - To run an executable from the virtual environment

Chain with `WithArgs` to pass arguments:

```csharp
builder.AddPythonScript("name", "dir", "script.py")
       .WithArgs("arg1", "arg2");
```

## AddPythonApp(IDistributedApplicationBuilder, string, string, string, string, string[])

> **Obsolete:** Use AddPythonScript, AddPythonModule, or AddPythonExecutable and chain with .WithVirtualEnvironment(...).WithArgs(...) instead.

- Name: `AddPythonApp(IDistributedApplicationBuilder, string, string, string, string, string[])`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PythonAppResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/a3766e994fd2cba86c8ac60b8a80268cab7e6383/src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs#L227-L231)

Adds a python application with a virtual environment to the application model.

```csharp
public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<PythonAppResource> AddPythonApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string scriptPath,
        string virtualEnvironmentPath,
        params string[] scriptArgs)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IDistributedApplicationBuilder`)
  The `Hosting.IDistributedApplicationBuilder` to add the resource to.
- `name` (`string`)
  The name of the resource.
- `appDirectory` (`string`)
  The path to the directory containing the python app files.
- `scriptPath` (`string`)
  The path to the script to run, relative to the app directory.
- `virtualEnvironmentPath` (`string`)
  Path to the virtual environment.
- `scriptArgs` (`string[]`)
  The arguments for the script.

## Returns

`IResourceBuilder<PythonAppResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Remarks

This overload is obsolete. Use one of the more specific methods instead:

- [PythonAppResourceBuilderExtensions.AddPythonApp(IDistributedApplicationBuilder, string, string, string)](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods.md#addpythonapp-idistributedapplicationbuilder-string-string-string) - To run a Python script file
- [PythonAppResourceBuilderExtensions.AddPythonModule(IDistributedApplicationBuilder, string, string, string)](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods.md#addpythonmodule-idistributedapplicationbuilder-string-string-string) - To run a Python module via `python -m`
- [PythonAppResourceBuilderExtensions.AddPythonExecutable(IDistributedApplicationBuilder, string, string, string)](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods.md#addpythonexecutable-idistributedapplicationbuilder-string-string-string) - To run an executable from the virtual environment

Chain with [PythonAppResourceBuilderExtensions.WithVirtualEnvironment(IResourceBuilder<T>, string, bool)](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods.md#withvirtualenvironment-iresourcebuilder-t-string-bool) and `WithArgs`:

```csharp
builder.AddPythonScript("name", "dir", "script.py")
       .WithVirtualEnvironment("myenv")
       .WithArgs("arg1", "arg2");
```

## AddPythonExecutable(IDistributedApplicationBuilder, string, string, string)

- Name: `AddPythonExecutable(IDistributedApplicationBuilder, string, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PythonAppResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/a3766e994fd2cba86c8ac60b8a80268cab7e6383/src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs#L149)

Adds a Python executable to the application model.

```csharp
public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<PythonAppResource> AddPythonExecutable(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string executableName)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IDistributedApplicationBuilder`)
  The `Hosting.IDistributedApplicationBuilder` to add the resource to.
- `name` (`string`)
  The name of the resource.
- `appDirectory` (`string`)
  The path to the directory containing the python application.
- `executableName` (`string`)
  The name of the executable in the virtual environment (e.g., "pytest", "uvicorn", "flask").

## Returns

`IResourceBuilder<PythonAppResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method runs an executable from the virtual environment's bin directory. By default, the virtual environment folder is expected to be named `.venv` and located in the app directory. Use [PythonAppResourceBuilderExtensions.WithVirtualEnvironment(IResourceBuilder<T>, string, bool)](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods.md#withvirtualenvironment-iresourcebuilder-t-string-bool) to specify a different virtual environment path. Use `WithArgs` to pass arguments to the executable.

Unlike scripts and modules, Python executables do not have debugging support enabled by default. Use [PythonAppResourceBuilderExtensions.WithDebugging(IResourceBuilder<T>)](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods.md#withdebugging-iresourcebuilder-t) to explicitly enable debugging support if the executable is a Python-based tool that can be debugged.

## Examples

Add a pytest executable to the application model:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddPythonExecutable("pytest", "../api", "pytest")
       .WithArgs("-q")
       .WithDebugging();

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## AddPythonModule(IDistributedApplicationBuilder, string, string, string)

- Name: `AddPythonModule(IDistributedApplicationBuilder, string, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<PythonAppResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/a3766e994fd2cba86c8ac60b8a80268cab7e6383/src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs#L108-L109)

Adds a Python module to the application model.

```csharp
public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<PythonAppResource> AddPythonModule(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string moduleName)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IDistributedApplicationBuilder`)
  The `Hosting.IDistributedApplicationBuilder` to add the resource to.
- `name` (`string`)
  The name of the resource.
- `appDirectory` (`string`)
  The path to the directory containing the python application.
- `moduleName` (`string`)
  The name of the Python module to run (e.g., "flask", "uvicorn").

## Returns

`IResourceBuilder<PythonAppResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method runs a Python module using `python -m <module>`. By default, the virtual environment folder is expected to be named `.venv` and located in the app directory. Use [PythonAppResourceBuilderExtensions.WithVirtualEnvironment(IResourceBuilder<T>, string, bool)](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods.md#withvirtualenvironment-iresourcebuilder-t-string-bool) to specify a different virtual environment path. Use `WithArgs` to pass arguments to the module.

Python modules automatically have debugging support enabled.

## Examples

Add a Flask module to the application model:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddPythonModule("flask-dev", "../flaskapp", "flask")
       .WithArgs("run", "--debug", "--host=0.0.0.0");

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## AddUvicornApp(IDistributedApplicationBuilder, string, string, string)

- Name: `AddUvicornApp(IDistributedApplicationBuilder, string, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<UvicornAppResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/a3766e994fd2cba86c8ac60b8a80268cab7e6383/src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs#L273-L333)

Adds a Uvicorn-based Python application to the distributed application builder with HTTP endpoint configuration.

```csharp
public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<UvicornAppResource> AddUvicornApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string app)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IDistributedApplicationBuilder`)
  The distributed application builder to which the Uvicorn application resource will be added.
- `name` (`string`)
  The unique name of the Uvicorn application resource.
- `appDirectory` (`string`)
  The directory containing the Python application files.
- `app` (`string`)
  The ASGI app import path which informs Uvicorn which module and variable to load as your web application. For example, "main:app" means "main.py" file and variable named "app".

## Returns

`IResourceBuilder<UvicornAppResource>` -- A resource builder for further configuration of the Uvicorn Python application resource.

## Remarks

This method configures the application to use Uvicorn as the ASGI server and exposes an HTTP endpoint. When publishing, it sets the entry point to use the Uvicorn executable with appropriate arguments for host and port.

By default, the virtual environment folder is expected to be named `.venv` and located in the app directory. Use [PythonAppResourceBuilderExtensions.WithVirtualEnvironment(IResourceBuilder<T>, string, bool)](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods.md#withvirtualenvironment-iresourcebuilder-t-string-bool) to specify a different virtual environment path.

In non-publish mode, the `--reload` flag is automatically added to enable hot reload during development.

## Examples

Add a FastAPI application using Uvicorn:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddUvicornApp("api", "../fastapi-app", "main:app")
    .WithUv()
    .WithExternalHttpEndpoints();

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithDebugging(IResourceBuilder<T>)

- Name: `WithDebugging(IResourceBuilder<T>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/a3766e994fd2cba86c8ac60b8a80268cab7e6383/src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs#L927-L1028)

Enables debugging support for the Python application.

```csharp
public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithDebugging<T>(
        this IResourceBuilder<T> builder)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for method chaining.

## Remarks

This method adds the `Python.PythonExecutableDebuggableAnnotation` to the resource, which enables debugging support. The debugging configuration is automatically set up based on the entrypoint type (Script, Module, or Executable).

The debug configuration includes the Python interpreter path from the virtual environment, the program or module to debug, and appropriate launch settings.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithEntrypoint(IResourceBuilder<T>, EntrypointType, string)

- Name: `WithEntrypoint(IResourceBuilder<T>, EntrypointType, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/a3766e994fd2cba86c8ac60b8a80268cab7e6383/src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs#L1066-L1124)

Configures the entrypoint for the Python application.

```csharp
public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEntrypoint<T>(
        this IResourceBuilder<T> builder,
        EntrypointType entrypointType,
        string entrypoint)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `entrypointType` ([EntrypointType](/reference/api/csharp/aspire.hosting.python/entrypointtype.md))
  The type of entrypoint (Script, Module, or Executable).
- `entrypoint` (`string`)
  The entrypoint value (script path, module name, or executable name).

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for method chaining.

## Remarks

This method allows you to change the entrypoint configuration of a Python application after it has been created. The command and arguments will be updated based on the specified entrypoint type:

- Script: Runs as `python <scriptPath>`
- Module: Runs as `python -m <moduleName>`
- Executable: Runs the executable directly from the virtual environment

Important: This method resets all command-line arguments. If you need to add arguments after changing the entrypoint, call `WithArgs` after this method.

## Examples

Change a Python app from running a script to running a module:

```csharp
var python = builder.AddPythonScript("api", "../python-api", "main.py")
    .WithEntrypoint(EntrypointType.Module, "uvicorn")
    .WithArgs("main:app", "--reload");
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithPip(IResourceBuilder<T>, bool, string[]?)

- Name: `WithPip(IResourceBuilder<T>, bool, string[]?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/a3766e994fd2cba86c8ac60b8a80268cab7e6383/src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs#L1164-L1207)

Configures the Python resource to use pip as the package manager and optionally installs packages before the application starts.

```csharp
public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithPip<T>(
        this IResourceBuilder<T> builder,
        bool install = true,
        string[]? installArgs = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `install` (`bool`) `optional`
  When true (default), automatically installs packages before the application starts. When false, only sets the package manager annotation without creating an installer resource.
- `installArgs` (`string[]?`) `optional`
  The command-line arguments passed to pip install command.

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for method chaining.

## Exceptions

- `ArgumentNullException` -- Thrown when `builder` is null.

## Remarks

This method creates a child resource that runs `pip install` in the working directory of the Python application. The Python application will wait for this resource to complete successfully before starting.

Pip will automatically detect and use either pyproject.toml or requirements.txt based on which file exists in the application directory. If pyproject.toml exists, pip will use it. Otherwise, if requirements.txt exists, pip will use that. Calling this method will replace any previously configured package manager (such as uv).

## Examples

Add a Python app with automatic pip package installation:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonScript("api", "../python-api", "main.py")
    .WithPip()  // Automatically installs from pyproject.toml or requirements.txt
    .WithHttpEndpoint(port: 5000);

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithUv(IResourceBuilder<T>, bool, string[]?)

- Name: `WithUv(IResourceBuilder<T>, bool, string[]?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/a3766e994fd2cba86c8ac60b8a80268cab7e6383/src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs#L1262-L1276)

Adds a UV environment setup task to ensure the virtual environment exists before running the Python application.

```csharp
public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithUv<T>(
        this IResourceBuilder<T> builder,
        bool install = true,
        string[]? args = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `install` (`bool`) `optional`
  When true (default), automatically runs uv sync before the application starts. When false, only sets the package manager annotation without creating an installer resource.
- `args` (`string[]?`) `optional`
  Optional custom arguments to pass to the uv command. If not provided, defaults to ["sync"].

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for method chaining.

## Exceptions

- `ArgumentNullException` -- Thrown when `builder` is null.

## Remarks

This method creates a child resource that runs `uv sync` in the working directory of the Python application. The Python application will wait for this resource to complete successfully before starting.

UV (https://github.com/astral-sh/uv) is a modern Python package manager written in Rust that can manage virtual environments and dependencies with significantly faster performance than traditional tools. The `uv sync` command ensures that the virtual environment exists, Python is installed if needed, and all dependencies specified in pyproject.toml are installed and synchronized.

Calling this method will replace any previously configured package manager (such as pip).

## Examples

### Example 1

Add a Python app with automatic UV environment setup:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonScript("api", "../python-api", "main.py")
    .WithUv()  // Automatically runs 'uv sync' before starting the app
    .WithHttpEndpoint(port: 5000);

builder.Build().Run();
```

### Example 2

Add a Python app with custom UV arguments:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonScript("api", "../python-api", "main.py")
    .WithUv(args: ["sync", "--python", "3.12", "--no-dev"])  // Custom uv sync args
    .WithHttpEndpoint(port: 5000);

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithVirtualEnvironment(IResourceBuilder<T>, string, bool)

- Name: `WithVirtualEnvironment(IResourceBuilder<T>, string, bool)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/a3766e994fd2cba86c8ac60b8a80268cab7e6383/src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs#L866-L903)

Configures a custom virtual environment path for the Python application.

```csharp
public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithVirtualEnvironment<T>(
        this IResourceBuilder<T> builder,
        string virtualEnvironmentPath,
        bool createIfNotExists = true)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `virtualEnvironmentPath` (`string`)
  The path to the virtual environment. Can be absolute or relative to the app directory. When relative, it is resolved from the working directory of the Python application. Common values include ".venv", "venv", or "myenv".
- `createIfNotExists` (`bool`) `optional`
  Whether to automatically create the virtual environment if it doesn't exist. Defaults to `true`. Set to `false` to disable automatic venv creation (the venv must already exist).

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for method chaining.

## Remarks

This method updates the Python executable path to use the specified virtual environment.

By default ( `createIfNotExists` = `true`), if the virtual environment doesn't exist, it will be automatically created before running the application (when using pip package manager, not uv). Set `createIfNotExists` to `false` to disable this behavior and require the venv to already exist.

Virtual environments allow Python applications to have isolated dependencies separate from the system Python installation. This is the recommended approach for Python applications.

When you explicitly specify a virtual environment path using this method, the path is used verbatim. The automatic multi-location lookup (checking both app and AppHost directories) only applies when using the default ".venv" path during initial app creation via AddPythonScript, AddPythonModule, or AddPythonExecutable.

## Examples

Configure a Python app to use a custom virtual environment:

```csharp
var python = builder.AddPythonApp("api", "../python-api", "main.py")
    .WithVirtualEnvironment("myenv");

// Disable automatic venv creation (require venv to exist)
var python2 = builder.AddPythonApp("api2", "../python-api2", "main.py")
    .WithVirtualEnvironment("myenv", createIfNotExists: false);
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.