Python.NET

3.0.5 · active · verified Fri Apr 10

Python.NET (pythonnet) is a package that provides nearly seamless integration between Python and the .NET Framework, .NET Core, and Mono runtime on Windows, Linux, and macOS. It allows Python programmers to script .NET applications or build entire applications using .NET services and components written in any CLR-targeting language (C#, VB.NET, F#, C++/CLI). The current version is 3.0.5 and it maintains an active release cadence with support for recent Python and .NET versions.

Warnings

breaking Python.NET 3.x dropped implicit assembly loading. All .NET assemblies (except possibly some core ones implicitly handled) must now be explicitly loaded using `clr.AddReference('AssemblyName')` before their types can be imported.
Fix: Ensure `clr.AddReference('YourAssembly')` is called for every .NET assembly you intend to use. Place relevant assembly directories in `sys.path` if they are not in the GAC or application base.
breaking In Python.NET 3.x, the conversion behavior for .NET enums and interface return types has changed. .NET enums are no longer implicitly converted to integers, and methods returning interfaces might require explicit casting to their concrete implementation types.
Fix: For enums, use enum members directly (e.g., `MyEnum.Option`) or the enum constructor (e.g., `MyEnum(42)`). For interfaces, use explicit conversion like `ConcreteType(interface_instance)` if you need to access members specific to the concrete type.
gotcha The .NET runtime must be explicitly initialized using `pythonnet.load()` *before* `import clr`. Calling `import clr` first will implicitly load a default runtime, which might not be the desired one or could fail if not configured correctly.
Fix: Always call `from pythonnet import load; load('your_runtime_type')` at the beginning of your script, ensuring it executes before any `import clr` statements.
breaking Python.NET 3.0.0 dropped support for Python 2.x. It is only compatible with Python 3.7 and newer.
Fix: Migrate your Python code to Python 3.7 or a later supported version.
gotcha Python.NET 3.x no longer implicitly converts arbitrary Python objects to `System.Boolean`. This can lead to `TypeError` if you rely on Python's truthiness rules for .NET boolean contexts.
Fix: Explicitly convert Python objects to `bool` or `System.Boolean` before passing them to .NET methods expecting a boolean, or ensure the Python object itself is a `bool`.
gotcha Python's objects are all reference types, while .NET distinguishes between value types (like `int`, `struct`) and reference types (like `class`). When a .NET value type is used in a context expecting a reference type, it might be 'boxed' into an object on the heap, leading to copies rather than direct modification if not handled carefully.
Fix: Be aware of the distinction between .NET value and reference types when working with .NET objects in Python. If modifying a value type, ensure you are working with the correct instance or reassigning the modified value.

Install

pip install pythonnet Install from PyPI

Imports

clr
```
import clr
```
While Python.Runtime is the underlying C# assembly, in Python you import `clr` directly after `pythonnet.load()`.
load
```
from pythonnet import load
```
The `load` function for runtime configuration is exposed directly under the `pythonnet` top-level package and must be called before `import clr`.

Quickstart

This quickstart demonstrates how to initialize the .NET runtime, add a reference to a .NET assembly, and then import and use .NET types and objects directly from Python. It explicitly handles potential runtime loading issues by trying different runtime types.

import pythonnet

# It's crucial to load the .NET runtime explicitly before importing 'clr'.
# Options: "coreclr" (modern cross-platform .NET), "netfx" (Windows .NET Framework), "mono" (Linux/macOS Mono).
# The choice depends on your OS and installed .NET environment.
# For this example, we'll try 'coreclr' first, then 'netfx' as a common fallback for Windows.

try:
    pythonnet.load("coreclr") # For .NET Core / .NET 5+ SDK installed
except RuntimeError:
    print("Could not load 'coreclr'. Trying 'netfx' (Windows only).")
    try:
        pythonnet.load("netfx") # For .NET Framework on Windows
    except RuntimeError:
        print("Could not load 'netfx'. Trying 'mono' (Linux/macOS fallback).")
        try:
            pythonnet.load("mono") # For Mono runtime
        except RuntimeError:
            print("Failed to load any .NET runtime. Ensure a compatible .NET SDK or Mono is installed.")
            import sys; sys.exit(1)

import clr
# Explicitly add a reference to a .NET assembly. 'System' is fundamental.
clr.AddReference("System")

# Now you can import types from the .NET System namespace
from System import DateTime
from System import Environment

print(f"Current Date and Time from .NET: {DateTime.Now}")
print(f".NET OS Version: {Environment.OSVersion.VersionString}")

# Example of creating a .NET object
from System.Collections.Generic import List
my_list = List[str]()
my_list.Add("Hello")
my_list.Add(".NET")

print(f"Items in .NET List: {', '.join(my_list)}")

view raw JSON →