Registry / serialization / clr-loader

clr-loader

JSON →
library0.3.1pypypi✓ verified 26d ago

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.

pip install clr-loader
INSTALL
IMPORT
SIG · CLR-LOADER
C
clr-loader
serializationpythonv0.3.1
Install
1.9s avg
Import
99ms
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.100s · 19.6MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.9s · import 0.098s · 20MB
18MB installed
● package 18MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

get_coreclr
from clr_loader import get_coreclr
from clr_loader.hostfxr import get_coreclr
The top-level import is the stable public API; direct imports from submodules like 'hostfxr' are considered internal and may change without warning.
get_mono
from clr_loader import get_mono
from clr_loader.mono import get_mono
Similar to get_coreclr, use the top-level import for stability.
ClrError
from clr_loader.exceptions import ClrError
Specific exception for runtime loading failures.

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.

import os from clr_loader import get_coreclr from clr_loader.exceptions import ClrError # clr-loader attempts to find the latest installed CoreCLR runtime. # This might require a .NET SDK or runtime to be installed on the system. # For CI/CD or specific versions, you might need to provide `runtime_config`. try: print("Attempting to load CoreCLR runtime...") # This call tries to auto-discover an installed .NET runtime. # If no .NET runtime is installed or discoverable, this will raise ClrError. clr_runtime_host = get_coreclr() print(f"Successfully loaded CoreCLR host: {clr_runtime_host}") # For advanced usage, one would then use clr_runtime_host # to load assemblies and interact with them, typically via pythonnet. # Example (conceptual, requires a .NET assembly and more setup): # assembly_path = os.path.join(os.getcwd(), "MyDotNetLib.dll") # loaded_assembly = clr_runtime_host.load_assembly_from(assembly_path.encode('utf-8')) # print(f"Loaded assembly: {loaded_assembly.name}") except ClrError as e: print(f"Error loading CoreCLR: {e}") print("This typically means a .NET runtime (e.g., .NET SDK or runtime) is not installed") print("or not discoverable on your system. Please install .NET and ensure it's in PATH,") print("or provide a specific runtime_config.json path to get_coreclr().") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingclr-loader version 0.3.0 and newer explicitly require Python 3.10 or higher. Older Python versions are no longer supported.
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).
affects: >=0.3.0
gotchaclr-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.
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()`.
affects: all
gotchaWhile 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.
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`.
affects: all
gotchaThe 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.
fix
Always import `get_coreclr` and `get_mono` directly from the top-level `clr_loader` package (e.g., `from clr_loader import get_coreclr`).
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'clr_loader'
The 'clr-loader' package is not installed in the active Python environment or the environment is not correctly configured to find it. This often occurs even if 'pythonnet' is installed, as 'clr-loader' is a distinct dependency.
fix
Ensure 'clr-loader' is correctly installed using `pip install clr-loader`. If using a specific virtual environment (e.g., Anaconda), activate that environment before installation. A Python kernel or IDE restart might be necessary to recognize the newly installed package.
Failed to load CoreCLR runtime
The `clr-loader` library cannot locate or initialize the necessary .NET runtime (CoreCLR, Mono, or Full .NET Framework) or its native components like `ClrLoader.dll`. This can be due to a missing .NET SDK/Runtime installation, incorrect environment variables (e.g., `DOTNET_ROOT` not set), or issues when packaging applications.
fix
Verify that the appropriate .NET SDK or Runtime is installed on your system. For CoreCLR, ensure the `DOTNET_ROOT` environment variable is set to the correct installation path. For packaged applications (e.g., with PyInstaller), confirm that `ClrLoader.dll` and other required runtime files are correctly bundled and accessible by the executable.
AttributeError: module 'clr_loader' has no attribute 'wrappers'
This error typically indicates an incompatibility between the installed versions of `clr-loader` and `pythonnet`, or with the Python version being used. An older `clr-loader` might lack attributes expected by a newer `pythonnet`, or vice-versa, especially with Python 3.10+.
fix
Upgrade your `pythonnet` installation to a version compatible with `clr-loader` 0.3.0 and Python 3.10+. This can often be resolved by running `pip install --upgrade --pre pythonnet` to get the latest compatible pre-release or stable version of pythonnet.
Could not load file or assembly '...' or one of its dependencies.
After `clr-loader` successfully initializes the .NET runtime, the subsequent attempt to load a specific .NET assembly (DLL) fails. This is commonly caused by the target assembly itself, or one of its dependencies, not being found, having a version mismatch, or encountering an architecture (x86/x64) conflict.
fix
Ensure that the .NET assembly you are trying to load, along with all its dependent DLLs, are present in the application's execution directory or a location discoverable by the .NET runtime. Check for x86/x64 architecture mismatches between your Python environment, `clr-loader`, and the .NET assembly. For detailed diagnostics, use the .NET Fusion Log Viewer (`fuslogvw.exe`) to understand assembly binding failures.
Upgrade
Version history
0.3.1latest on PyPI · released Apr 18, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
37 hits · last 30 days
node
34
OpenAI (training)
1
Resources
clr-loader — pip install clr-loader · libregistry