{"id":2437,"library":"clr-loader","title":"CLR Loader","description":"clr-loader is a pure Python library designed for loading .NET runtimes (CoreCLR, Mono, Full .NET Framework), loading .NET assemblies, and interacting with them. It primarily serves as a low-level backend for the pythonnet library but can be used standalone for specific scenarios. Version 0.3.0 is the current release, requiring Python 3.10 or newer. Releases are made on an as-needed basis, often in sync with pythonnet development.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/pythonnet/clr-loader","tags":["dotnet","clr","mono","coreclr","interop","pythonnet","low-level"],"install":[{"cmd":"pip install clr-loader","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The top-level import is the stable public API; direct imports from submodules like 'hostfxr' are considered internal and may change without warning.","wrong":"from clr_loader.hostfxr import get_coreclr","symbol":"get_coreclr","correct":"from clr_loader import get_coreclr"},{"note":"Similar to get_coreclr, use the top-level import for stability.","wrong":"from clr_loader.mono import get_mono","symbol":"get_mono","correct":"from clr_loader import get_mono"},{"note":"Specific exception for runtime loading failures.","symbol":"ClrError","correct":"from clr_loader.exceptions import ClrError"}],"quickstart":{"code":"import os\nfrom clr_loader import get_coreclr\nfrom clr_loader.exceptions import ClrError\n\n# clr-loader attempts to find the latest installed CoreCLR runtime.\n# This might require a .NET SDK or runtime to be installed on the system.\n# For CI/CD or specific versions, you might need to provide `runtime_config`.\n\ntry:\n    print(\"Attempting to load CoreCLR runtime...\")\n    # This call tries to auto-discover an installed .NET runtime.\n    # If no .NET runtime is installed or discoverable, this will raise ClrError.\n    clr_runtime_host = get_coreclr()\n    print(f\"Successfully loaded CoreCLR host: {clr_runtime_host}\")\n\n    # For advanced usage, one would then use clr_runtime_host\n    # to load assemblies and interact with them, typically via pythonnet.\n    # Example (conceptual, requires a .NET assembly and more setup):\n    # assembly_path = os.path.join(os.getcwd(), \"MyDotNetLib.dll\")\n    # loaded_assembly = clr_runtime_host.load_assembly_from(assembly_path.encode('utf-8'))\n    # print(f\"Loaded assembly: {loaded_assembly.name}\")\n\nexcept ClrError as e:\n    print(f\"Error loading CoreCLR: {e}\")\n    print(\"This typically means a .NET runtime (e.g., .NET SDK or runtime) is not installed\")\n    print(\"or not discoverable on your system. Please install .NET and ensure it's in PATH,\")\n    print(\"or provide a specific runtime_config.json path to get_coreclr().\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"This example attempts to load the CoreCLR runtime automatically. It demonstrates the most basic interaction with clr-loader and includes error handling for common setup issues, specifically the absence of a discoverable .NET runtime on the system. Advanced usage, such as loading specific assemblies or interacting with .NET objects, typically involves the pythonnet library built on top of clr-loader."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or later, or use an older version of clr-loader if compatible with your Python version and needs (though not recommended for long-term projects).","message":"clr-loader version 0.3.0 and newer explicitly require Python 3.10 or higher. Older Python versions are no longer supported.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Ensure a compatible .NET runtime is installed on your system. For CoreCLR, this typically means installing a .NET SDK or Runtime, which should make `dotnet` command available in your PATH. If auto-discovery fails, you might need to provide `runtime_config` or `home_directory` arguments to `get_coreclr()`.","message":"clr-loader is a loader, not a runtime provider. It requires a .NET runtime (e.g., .NET Core SDK, .NET Runtime, or Mono) to be installed and discoverable on the system. The library itself does not bundle or install a .NET runtime.","severity":"gotcha","affected_versions":"all"},{"fix":"For most use cases involving interacting with .NET libraries from Python, consider using `pythonnet` which provides a high-level API built on `clr-loader`.","message":"While clr-loader can be used standalone, its primary purpose is to be a low-level backend for pythonnet. Direct interaction with loaded assemblies and .NET objects in a user-friendly Pythonic way is best achieved through pythonnet, which leverages clr-loader internally.","severity":"gotcha","affected_versions":"all"},{"fix":"Always import `get_coreclr` and `get_mono` directly from the top-level `clr_loader` package (e.g., `from clr_loader import get_coreclr`).","message":"The public API for loading runtimes are `clr_loader.get_coreclr()` and `clr_loader.get_mono()`. Directly importing from submodules like `clr_loader.hostfxr` or `clr_loader.mono` is not part of the stable public API and can lead to breaking changes in minor versions.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}