Python integration

Este conteúdo não está disponível em sua língua ainda.

The Aspire Python hosting integration enables you to run Python applications alongside your Aspire projects in the Aspire app host. This integration provides first-class support for Python apps, scripts, modules, executables, and web frameworks like FastAPI.

Hosting integration

To access these types and APIs for expressing Python resources in your AppHost project, install the 📦 Aspire.Hosting.Python NuGet package:

aspire add python

A CLI Aspire é interativa; escolhe o resultado apropriado quando solicitado:

Select an integration to add:

> python (Aspire.Hosting.Python)
> Other results listed as selectable options...

#:package Aspire.Hosting.Python@*

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

Add Python app

To add a Python application to your app host, use the AddPythonApp extension method to run a Python script:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonApp(
    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 AddPythonApp 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)

Add Python module

To run a Python module (using python -m), use the AddPythonModule extension method:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonModule(
    name: "python-module",
    projectDirectory: "../python-app",
    moduleName: "mymodule")
    .WithHttpEndpoint(port: 8000, env: "PORT");

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

The AddPythonModule method requires:

name: The name of the resource in the Aspire dashboard
projectDirectory: The path to the directory containing your Python application
moduleName: The name of the Python module to run

Add Python executable

To run a Python executable or CLI tool from a virtual environment, use the AddPythonExecutable extension method:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonExecutable(
    name: "python-tool",
    projectDirectory: "../python-app",
    executable: "uvicorn",
    args: ["main:app", "--host", "0.0.0.0", "--port", "8000"]);

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

Add Uvicorn app

For ASGI web frameworks like FastAPI, Starlette, and Quart, use the AddUvicornApp extension method which provides built-in support for Uvicorn:

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)

Uvicorn configuration

The AddUvicornApp method supports additional configuration options:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddUvicornApp("python-api", "../python-app", "main:app")
    .WithHttpEndpoint(port: 8000, env: "PORT")
    .WithEnvironment("UVICORN_WORKERS", "4")
    .WithEnvironment("UVICORN_LOG_LEVEL", "info");

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

Common Uvicorn environment variables:

UVICORN_PORT: The port to listen on
UVICORN_HOST: The host to bind to (default: 127.0.0.1)
UVICORN_WORKERS: Number of worker processes
UVICORN_LOG_LEVEL: Logging level (e.g., debug, info, warning, error)

Virtual environment management

The Python hosting integration automatically detects and manages Python virtual environments:

Automatic virtual environment

By default, the integration looks for a virtual environment in the project directory. If a requirements.txt or pyproject.toml file is found, it will automatically create and activate a virtual environment.

var builder = DistributedApplication.CreateBuilder(args);

// Automatically detects and uses virtual environment
var python = builder.AddPythonApp("python-api", "../python-app", "main.py");

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

Custom virtual environment

To specify a custom virtual environment location, use the WithVirtualEnvironment method:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonApp("python-api", "../python-app", "main.py")
    .WithVirtualEnvironment("../python-app/.venv");

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

Disable virtual environment

To disable automatic virtual environment creation, use the WithoutVirtualEnvironment method:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonApp("python-api", "../python-app", "main.py")
    .WithoutVirtualEnvironment();

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

Package management

The Python hosting integration supports multiple package managers and allows you to choose which one to use:

Using uv package manager

Use the WithUv() method to explicitly use the uv package manager for faster dependency installation:

var builder = DistributedApplication.CreateBuilder(args);

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

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

The WithUv() method configures the Python app to use uv for package management, which is significantly faster than pip and recommended for new projects.

Using pip package manager

Use the WithPip() method to explicitly use pip for package management:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonApp("python-api", "../python-app", "main.py")
    .WithPip()
    .WithHttpEndpoint(port: 8000, env: "PORT");

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

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: "PORT");

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

Multiple endpoints

You can configure multiple endpoints for a Python application:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonApp("python-api", "../python-app", "main.py")
    .WithHttpEndpoint(port: 8000, env: "HTTP_PORT", name: "http")
    .WithHttpEndpoint(port: 8443, env: "HTTPS_PORT", name: "https");

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

Health checks

The Python hosting integration supports health checks for monitoring service health:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Environment variables

Pass environment variables to your Python application using the WithEnvironment method:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonApp("python-api", "../python-app", "main.py")
    .WithEnvironment("DEBUG", "true")
    .WithEnvironment("LOG_LEVEL", "debug");

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

Service discovery

Python applications can reference other services in the Aspire app host using service discovery:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
    .AddDatabase("mydb");

var python = builder.AddPythonApp("python-api", "../python-app", "main.py")
    .WithReference(postgres);

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

The connection string will be available as an environment variable in the Python application.

Debugging

The Python hosting integration provides full debugging support in Visual Studio Code:

Install the Aspire VS Code extension
Set breakpoints in your Python code
Run the Aspire app host
The debugger will automatically attach to your Python application

Deployment

When deploying your Aspire application, the Python hosting integration automatically generates production-ready Dockerfiles for your Python services:

# Auto-generated Dockerfile
FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "main.py"]