Running Python packages from PyPI

IronPython can be used in a variety of ways, for variety of purposes. The main one is as a .NET language, allowing to write .NET programs in the Python language, providing access to almost all of the .NET library, directly from Python code.

In the opposite direction, it is capable of running Python modules and packages, thus allowing .NET programs written in C#, or any other .NET language, to leverage the existing ecosystem of Python packages. But this scenario comes with some caveats — not every Python package can be used with IronPython. So the common question is "Will my favorite package from PyPI run in IronPython?" Unfortunately, a short answer is "it depends." The only sure way of knowing is to try. If it works — great, please update the list of Python packages known to work with IronPython. If it doesn't, then it is still possible to get it running, depending on the type of error generated. It may be a bug in IronPython, which can be addressed. Or it may be a showstopper when the package depends on some aspect of a specific implementation by CPython (Python implementation in C). This document intends to describe what are the success factors, what to expect with packages not listed in the "Package compatibility" document, how to understand errors and possibly report them to the project.

Note

Before installing a Python module from PyPI, first perform a one-time preparation of a fresh IronPython installation or environment:

ipy -m ensurepip
ipy -m pip install --upgrade pip
ipy -m pip install --upgrade setuptools

From the perspective of package compatibility with IronPython, packages can be grouped in the following categories:

Pure-Python packages

If the whole package is implemented only in Python, the chances are high it will work with IronPython. The main factor of success here is what version of Python the package requires. The current released version of IronPython is 3.4, but it doesn't mean that it supports exactly the same as as CPython 3.4. There are some language features from later version of Python implemented, and there is still a small set of less common language features of 3.4 or standard library 3.4 not fully implemented. There are also some intrinsic differences with CPython, which are unavoidable. Basically, the version number 3.4 with IronPython means that it comes with the Python Standard Library (StdLib) that was distributed with CPython 3.4, albeit with a few tweaks to make it compatible with IronPython. So the highest chance of success have packages targeting Python 3.4.

If you hit a problem due to some language feature from 3.4 (or earlier 3.x version) that is missing in IronPython, or some module from the StdLib that is not fully implemented, please consider submitting a problem report, and it will be given priority. Just keep in mind all package dependencies must satisfy the same constraint, including transitive dependencies. If your favourite package is in pure Python, but depends on a package that is a CPython extension (e.g. numpy), it is a roadblock.

Packages with a C backend

Some Python packages are actually just a layer on top of a C library, or use a C library for part of the functionality. The interface between Python and the underlying C code is supported by package ctypes, which is included with IronPython. Therefore such packages in principle should be able to run with IronPython, but because they depend on some 3rd party libraries, most often they do not come precompiled, but require a compilation of their C components during installation. This is supported by package setuptools, and this may or may not work depending how sophisticated the package setup scripts are. In general, because setuptools used with IronPython is the one for Python 3.4, trying to install a package that requires a later Python may not succeed, even if IronPython implements all Python language features used by the package, simply because that version of setuptools is unable to handle the installation scripts.

Packages that are CPython extensions

Some packages contain a C backend that depends on the implementation of the CPython engine itself. There is no CPython engine in IronPython, so obviously this will not work. A notable example of such package is numpy. There is a project Ironclad that aims at providing a CPython emulation layer on top of IronPython, but currently it has no working code for IronPython 3.x. Contributors welcome. In the meantime, if your goal is to use such packages from within a .NET/C# program, you may want to check out other projects that achieve better compatibility with CPython by embedding a complete CPython engine within a .NET process:

• Python.NET
• CSnakes

There is no point in reporting issues with such packages on the IronPython tracker, as it will never be implemented in IronPython. Such issues belong to the Ironclad project, which strives at providing this compatibility layer. However, you are welcome to record such packages on the wiki page Package compatibility to help other developers wondering the same.

Here are some clues to help identify if the package is a CPython extension package:

• The C code contains #include <Python.h>. This header file exports symbols from the CPython dynamic library.
• It loads libpythonX.Y.so, or libpythonX.Y.dylib, pythonX.dll or pythonXY.dll (depending on the operating system, X and Y being Python version numbers), which contains the CPython engine.
• The Python code refers to PyDLL, pydll, or pythonapi from package ctypes, which provide access to the CPython engine from Python code.