Installation

Fully self-contained package (easier install)

This is supported only on Windows x64, Linux x64 and macOS x64.

npm i pymport

This will install the pre-built pymport binaries and a self-contained Python 3.11 environment.

You should use pympip3 (or npx pympip3 if node_modules/.bin is not in your PATH) to install packages into this environment. Running pympip3 show pip will show you where these packages live.

pympip3 is simply a redirection to node_modules/pymport/lib/binding/<platform>/python -m pip.

Using an existing Python environment (more compatible and more robust)

npm i pymport --build-from-source

This will download and rebuild pymport against your own already existing Python environment.

You will need a working node-gyp supported C++ development environment. Additionally, on Linux and macOS you will need that the python3-embed package in pkg-config works. For this, on Linux you will need the libpython3-dev package. On macOS the Homebrew install has everything required. On Windows you should have a working python command in your shell.

If you want to skip the Python library auto-detection and manually point it to an existing location, you can set CXXFLAGS and LIBS so that Python is accessible to the C++ compiler and then run

export CXXFLAGS="..."
export LIBS="..."
npm i pymport --build-from-source --external_python

If you need to reproduce the fully integrated Python build, you will need conan>=2.0.0 from pip and then you can run:

npm i pymport --build-from-source --builtin_python

node-gyp has first class support for g++ on Linux, clang on macOS and MSVC 2019 on Windows. It also has a somewhat lower grade support for clang on Linux and on Windows.

When rebuilding from source, you should be particularly mindful of mismatching versions of the underlying libraries. In particular, if your Python interpreter and pymport are built against OpenSSL 3.0 you will get random crashes if trying to use it on Node.js 16.x which is typically built with OpenSSL 1.1.

Using an existing Python environment without rebuilding from source (risky)

This is valid on all OS, but it concerns mostly Windows users without a working C++ environment.

After installing the self-contained package, you can set the PYTHONHOME/PYTHONPATH variables to point Python to your existing environment. This requires having the same minor version of Python as the built-in module, as Python libraries are not compatible across different minor versions. If the version is an exact match, you don't need to do anything. If the patch versions differ, it is highly recommended to use the Python interpreter shared library that comes with your Python installation instead of the one bundled with the module - by setting LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS). On Windows, make sure that PATH is set accordingly.