Python interop, reimagined for modern .NET ✨

// .NET ↔ Python in 4 lines
var executor = Python.GetInstance();
var temperatures = new[] { 23.5, 19.2, 31.8, 27.4, 22.1 };
using var result = executor.ExecuteAndCapture(@"
    import statistics
    result = {'mean': statistics.mean(data), 'stdev': statistics.stdev(data)}
", new Dictionary<string, object?> { { "data", temperatures } });
Console.WriteLine($"Mean: {result?.GetDouble("mean"):F1}°C ± {result?.GetDouble("stdev"):F1}");

✅ Native AOT Support | ✅ .NET 10 File-based Apps | ✅ Declarative uv Integration | ✅ Built-in Security

DotNetPy (pronounced dot-net-pie) is a .NET library that allows you to seamlessly execute Python code directly from your C# applications. It provides a simple and intuitive API to run Python scripts and evaluate expressions with minimal boilerplate.

DotNetPy is built around three core principles:

Write Python code as strings within your C# code, with full control over execution and data flow. No separate Python files, no Source Generators, no complex setup — just define your Python logic inline and execute it.

// Define and execute Python declaratively from C#
using var result = executor.ExecuteAndCapture(@"
    import statistics
    result = {'mean': statistics.mean(data), 'stdev': statistics.stdev(data)}
", new Dictionary<string, object?> { { "data", myNumbers } });

Designed from the ground up for modern .NET scenarios:

• File-based Apps (.NET 10+): Works perfectly with dotnet run script.cs — no project file required
• Native AOT: The only .NET-Python interop library that supports PublishAot=true
• Minimal Dependencies: No heavy runtime requirements

# Just run it — no csproj needed
dotnet run my-script.cs

Declaratively manage Python environments using uv:

// Define your Python environment in C#
using var project = PythonProject.CreateBuilder()
    .WithProjectName("my-analysis")
    .WithPythonVersion(">=3.10")
    .AddDependencies("numpy>=1.24.0", "pandas>=2.0.0")
    .Build();

await project.InitializeAsync();  // Downloads Python, creates venv, installs packages

DotNetPy executes arbitrary Python code with the same privileges as the host .NET process. Never pass untrusted or user-provided input directly to execution methods.

// ❌ DANGEROUS: User input executed as code
executor.Execute(userInput); // Remote Code Execution vulnerability!

// ✅ SAFE: User data passed as variables, not code
executor.Execute("result = sum(numbers)", new Dictionary<string, object?> { { "numbers", userNumbers } });

DotNetPy includes a built-in Roslyn analyzer that detects potential code injection at compile time.

📖 Full Security Guide →

• Automatic Python Discovery: Cross-platform automatic detection of installed Python distributions with configurable requirements (version, architecture).
• Runtime Information: Query and inspect the currently active Python runtime configuration.
• Execute Python Code: Run multi-line Python scripts.
• Evaluate Expressions: Directly evaluate single-line Python expressions and get the result.
• Data Marshaling:
  • Pass complex .NET objects (like arrays and dictionaries) to Python.
  • Convert Python objects (including dictionaries, lists, numbers, and strings) back into .NET types.
• Variable Management:
  • ExecuteAndCapture: Execute code and capture a specific variable (by convention, result) into a .NET object.
  • CaptureVariable(s): Capture one or more global variables from the Python session after execution.
  • DeleteVariable(s): Remove variables from the Python session.
  • VariableExists: Check if a variable exists in the Python session.
  • GetExistingVariables: Returns a list of variables that actually exist from a given list of variable names.
  • ClearGlobals: Clear all global variables from the Python session.
• Free-threaded Python Support: Detects and reports Python 3.13+ builds with --disable-gil (experimental free-threading).
• No Boilerplate: The library handles the complexities of the Python C API, providing a clean interface.

• .NET 8.0 or later.
• A Python installation (e.g., Python 3.13). You will need the path to the Python shared library (pythonXX.dll on Windows, libpythonX.X.so on Linux).
• (Optional) uv for declarative environment management.

To start using DotNetPy, you need to initialize the Python engine with the path to your Python library.

using DotNetPy;

// Path to your Python shared library
var pythonLibraryPath = Path.Combine(
    Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
    "Programs", "Python", "Python313", "python313.dll");

// Initialize the Python engine
Python.Initialize(pythonLibraryPath);

// Get an executor instance
var executor = Python.GetInstance();

// Evaluate expressions
var sum = executor.Evaluate("sum([1,2,3,4,5])")?.GetInt32(); // 15

// Execute scripts and capture results
using var result = executor.ExecuteAndCapture(@"
    import math
    result = {'sqrt': math.sqrt(16), 'pi': math.pi}
");
Console.WriteLine(result?.GetDouble("sqrt")); // 4

// Pass .NET data to Python
var numbers = new[] { 10, 20, 30 };
using var stats = executor.ExecuteAndCapture(@"
    result = {'sum': sum(data), 'avg': sum(data)/len(data)}
", new Dictionary<string, object?> { { "data", numbers } });

📖 Full Usage Examples →

Wondering how DotNetPy compares to pythonnet or CSnakes? Check out our detailed comparison guide to understand the differences and choose the right tool for your needs.

DotNetPy is thread-safe through Python's Global Interpreter Lock (GIL). Best suited for sequential execution, I/O-bound operations, and low-to-moderate concurrency scenarios.

📖 Performance & Concurrency Details →

Declaratively manage Python environments using uv:

using DotNetPy;
using DotNetPy.Uv;

// Define your Python project declaratively
using var project = PythonProject.CreateBuilder()
    .WithProjectName("my-data-analysis")
    .WithPythonVersion(">=3.10")
    .AddDependency("numpy", ">=1.24.0")
    .AddDependency("pandas", ">=2.0.0")
    .Build();

await project.InitializeAsync();  // Downloads Python, creates venv, installs packages

var executor = project.GetExecutor();
executor.Execute("import numpy as np; print(np.mean([1,2,3]))");

📖 Full uv Integration Guide →

Ready-to-run sample applications are available in the samples/ directory:

# Run the quickstart sample
cd samples/quickstart
dotnet run quickstart.cs

📖 All Samples →

📖 Testing Guide →

The following features are planned for future releases:

• ✅ Automatic Python Discovery (Completed): Cross-platform automatic detection and discovery of installed Python distributions, eliminating the need for manual library path configuration.
• ✅ Virtual Environment (venv) Support (Completed): Enhanced support for working with Python virtual environments, including automatic activation and package management via LoadVirtualEnvironment() extension method.
• ✅ uv Integration (Completed): Declarative Python environment management using the uv package manager with PythonProject and PythonProjectBuilder classes.
• Embeddable Python Support (Windows): Automatic setup and configuration of embeddable Python packages on Windows for simplified deployment scenarios.
• AI and Data Science Scenarios: Specialized support and optimizations for AI and data science workflows, including better integration with popular libraries like NumPy, Pandas, and machine learning frameworks.

This project is licensed under the Apache License 2.0. Please see the LICENSE.txt file for details.