aspire.dev/src/frontend/src/content/docs/integrations/frameworks/python.mdx at 7c9e6169fe6cb7cc23ace648dc5f19d892b82fd5 · microsoft/aspire.dev

title	Python integration
description	Learn how to use the Aspire Python Hosting integration to orchestrate Python applications in an Aspire solution.

import { Aside } from '@astrojs/starlight/components'; import InstallPackage from '@components/InstallPackage.astro'; import { Image } from 'astro:assets'; import pythonIcon from '@assets/icons/python.svg';

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.

:::tip[First-class Python support] As of Aspire 13, Python is a first-class workload with the Aspire.Hosting.Python package. The previous CommunityToolkit.Aspire.Hosting.Python.Extensions package is deprecated, and its functionality has been integrated into the official package with full support for debugging, service discovery, and deployment alongside .NET and JavaScript applications. :::

Hosting integration

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

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...

If neither WithUv() nor WithPip() is specified, Aspire will automatically detect the appropriate package manager based on your project configuration (pyproject.toml for uv, requirements.txt for pip).

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 is available as an environment variable named ConnectionStrings__mydb in the Python application. Access it with:

import os

connection_string = os.getenv("ConnectionStrings__mydb")

For more details on how resource names map to environment variable names, see Environment variables.

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

The Aspire VS Code extension automatically generates launch configurations for Python applications in your Aspire solution, enabling zero-configuration debugging.

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"]

The generated Dockerfile is tailored to your detected Python version and dependency setup, ensuring optimal compatibility and performance.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Hosting integration

Add Python app

Add Python module

Add Python executable

Add Uvicorn app

Uvicorn configuration

Virtual environment management

Automatic virtual environment

Custom virtual environment

Disable virtual environment

Package management

Using uv package manager

Using pip package manager

Configure endpoints

Multiple endpoints

Health checks

Environment variables

Service discovery

Debugging

Deployment

See also

FilesExpand file tree

python.mdx

Latest commit

History

python.mdx

File metadata and controls

Hosting integration

Add Python app

Add Python module

Add Python executable

Add Uvicorn app

Uvicorn configuration

Virtual environment management

Automatic virtual environment

Custom virtual environment

Disable virtual environment

Package management

Using uv package manager

Using pip package manager

Configure endpoints

Multiple endpoints

Health checks

Environment variables

Service discovery

Debugging

Deployment

See also