Python integration

⭐ Community Toolkit

The Aspire Python hosting integration enables you to run Python applications alongside your Aspire projects in the Aspire app host. This integration supports both Uvicorn applications and uv package manager applications.

Hosting integration

To get started with the Aspire Python hosting integration, install the CommunityToolkit.Aspire.Hosting.Python.Extensions NuGet package in the app host project.

aspire add communitytoolkit-python-extensions

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Select an integration to add:

> communitytoolkit-python-extensions (CommunityToolkit.Aspire.Hosting.Python.Extensions)
> Other results listed as selectable options...

#:package CommunityToolkit.Aspire.Hosting.Python.Extensions@*

<PackageReference Include="CommunityToolkit.Aspire.Hosting.Python.Extensions" Version="*" />

Add Uvicorn app

To add a Uvicorn application to your app host, use the AddUvicornApp extension method:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddUvicornApp(
    name: "python-api",
    projectDirectory: "../python-app",
    appName: "main:app")
    .WithHttpEndpoint(port: 8000, env: "PORT");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(python);

// After adding all resources, run the app...

The AddUvicornApp method requires:

name: The name of the resource in the Aspire dashboard
projectDirectory: The path to the directory containing your Python application
appName: The Python module and ASGI application instance (e.g., main:app for an app instance in main.py)

Add uv app

To add an application using the uv package manager, use the AddUvApp extension method:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddUvApp(
    name: "python-api",
    projectDirectory: "../python-app",
    scriptPath: "main.py")
    .WithHttpEndpoint(port: 8000, env: "PORT");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(python);

// After adding all resources, run the app...

The AddUvApp method requires:

name: The name of the resource in the Aspire dashboard
projectDirectory: The path to the directory containing your Python application
scriptPath: The path to the Python script to run (relative to the project directory)

Configure endpoints

Python applications typically use environment variables to configure the port they listen on. Use WithHttpEndpoint to configure the port and set the environment variable:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddUvicornApp("python-api", "../python-app", "main:app")
    .WithHttpEndpoint(port: 8000, env: "UVICORN_PORT");

// After adding all resources, run the app...

Common environment variables for Python web frameworks:

UVICORN_PORT: For Uvicorn applications
PORT: Generic port configuration used by many frameworks

Working directory

By default, the working directory is set to the projectDirectory specified when adding the Python app. The integration will look for the Python virtual environment and dependencies in this directory.