{"id":2738,"library":"pythonnet","title":"Python.NET","description":"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.","status":"active","version":"3.0.5","language":"en","source_language":"en","source_url":"https://github.com/pythonnet/pythonnet","tags":[".NET","CLR","interop","C#","F#","Mono"],"install":[{"cmd":"pip install pythonnet","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Requires a compatible .NET runtime (e.g., .NET Framework, .NET Core/.NET 5+, or Mono) to be installed on the system to function.","package":".NET Runtime","optional":false},{"reason":"Underlying library for loading CLR runtimes, though typically bundled with pythonnet.","package":"clr-loader","optional":false}],"imports":[{"note":"While Python.Runtime is the underlying C# assembly, in Python you import `clr` directly after `pythonnet.load()`.","wrong":"from Python.Runtime import clr","symbol":"clr","correct":"import clr"},{"note":"The `load` function for runtime configuration is exposed directly under the `pythonnet` top-level package and must be called before `import clr`.","wrong":"import clr; clr.load()","symbol":"load","correct":"from pythonnet import load"}],"quickstart":{"code":"import pythonnet\n\n# It's crucial to load the .NET runtime explicitly before importing 'clr'.\n# Options: \"coreclr\" (modern cross-platform .NET), \"netfx\" (Windows .NET Framework), \"mono\" (Linux/macOS Mono).\n# The choice depends on your OS and installed .NET environment.\n# For this example, we'll try 'coreclr' first, then 'netfx' as a common fallback for Windows.\n\ntry:\n    pythonnet.load(\"coreclr\") # For .NET Core / .NET 5+ SDK installed\nexcept RuntimeError:\n    print(\"Could not load 'coreclr'. Trying 'netfx' (Windows only).\")\n    try:\n        pythonnet.load(\"netfx\") # For .NET Framework on Windows\n    except RuntimeError:\n        print(\"Could not load 'netfx'. Trying 'mono' (Linux/macOS fallback).\")\n        try:\n            pythonnet.load(\"mono\") # For Mono runtime\n        except RuntimeError:\n            print(\"Failed to load any .NET runtime. Ensure a compatible .NET SDK or Mono is installed.\")\n            import sys; sys.exit(1)\n\nimport clr\n# Explicitly add a reference to a .NET assembly. 'System' is fundamental.\nclr.AddReference(\"System\")\n\n# Now you can import types from the .NET System namespace\nfrom System import DateTime\nfrom System import Environment\n\nprint(f\"Current Date and Time from .NET: {DateTime.Now}\")\nprint(f\".NET OS Version: {Environment.OSVersion.VersionString}\")\n\n# Example of creating a .NET object\nfrom System.Collections.Generic import List\nmy_list = List[str]()\nmy_list.Add(\"Hello\")\nmy_list.Add(\".NET\")\n\nprint(f\"Items in .NET List: {', '.join(my_list)}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"3.0.0 and later"},{"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.","message":"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.","severity":"breaking","affected_versions":"3.0.0 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All 3.x versions"},{"fix":"Migrate your Python code to Python 3.7 or a later supported version.","message":"Python.NET 3.0.0 dropped support for Python 2.x. It is only compatible with Python 3.7 and newer.","severity":"breaking","affected_versions":"3.0.0 and later"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"3.0.0 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}