Pythonx

Pythonx embeds the Python interpreter in the same OS process as your Elixir application using Erlang NIFs.

Concurrency Implications: Because of Python's Global Interpreter Lock (GIL), calling Pythonx from multiple Elixir processes does not provide true parallel execution of Python code. This can create bottlenecks.

When to use Pythonx vs other methods:

• Use Pythonx when: You need tight integration, easy data conversion between Elixir and Python, or when using libraries like numpy that release the GIL during heavy CPU tasks or I/O.
• Use System.cmd/3 or Ports when: You need to run multiple independent Python programs concurrently without GIL contention.

For permanent applications, add {:pythonx, "~> 0.4.0"} to your deps. Instead of manual initialization, configure the interpreter in config/config.exs using the :uv_init key. This ensures downloads happen at compile time and the interpreter initializes automatically on boot. This configuration is compatible with Elixir releases.

# config/config.exs
import Config

config :pythonx, :uv_init,
  pyproject_toml: """
  [project]
  name = "project"
  version = "0.0.0"
  requires-python = "==3.13.*"
  dependencies = [
    "numpy==2.2.2"
  ]
  """

# Optionally specify a uv version
config :pythonx, :uv_init, 
  uv_version: "0.7.21"

To use Pythonx in a standalone Elixir script, add it to your Mix.install dependencies. You must initialize the interpreter using Pythonx.uv_init/1 with a pyproject.toml string to specify the Python version and required dependencies. Once initialized, you can evaluate Python code using Pythonx.eval/2 and decode the results using Pythonx.decode/1.

Mix.install([
  {:pythonx, "~> 0.4.0"}
])

Pythonx.uv_init("""
[project]
name = "project"
version = "0.0.0"
requires-python = "==3.13.*"
dependencies = [
  "numpy==2.2.2"
]
""")

{result, globals} =
  Pythonx.eval(
    """
    y = 10
    x + y
    """,
    %{"x" => 1}
  )

Pythonx.decode(result)
#=> 11

Pythonx can be initialized in two ways:

1. Explicitly: Using Pythonx.uv_init/2.
2. Via Environment Variables: If the environment variable PYTHONX_INIT_STATE is set, Pythonx will automatically initialize on boot (useful for FLAME nodes).

Note on Environment Variables: Python's os.environ is initialized from the OS process environment. It does not reflect changes made via Elixir's System.put_env/2. To mirror Elixir environment variables to Python, you must set them on os.environ using Pythonx.eval/3.

The Pythonx.Object struct is an opaque container used to pass Python objects between Python and Elixir. It holds a reference to the underlying Python resource and metadata about its location.

When inspecting a Pythonx.Object in an Elixir shell or via IO.inspect/2, the library performs a remote call to Python to retrieve its string representation (__repr__), allowing you to see the Python object's content directly in your Elixir console.

#%Pythonx.Object{} is an opaque struct containing:
# :resource - The underlying resource handle
# :remote_info - Metadata about the remote object

Use Pythonx.uv_init/2 to install a Python interpreter and required dependencies using the uv package manager. You must provide a string containing the content of a pyproject.toml file. The configuration must include project.name and project.version fields. It is recommended to specify the Python version via project.requires-python.

Pythonx.uv_init("""
[project]
name = "project"
version = "0.0.0"
requires-python = "==3.13.*"
dependencies = [
  "numpy==2.2.2"
]
""")

In dynamic environments like IEx or Livebook, you can use the ~PY sigil to evaluate Python code. This requires importing Pythonx. The sigil allows you to reference Elixir variables directly within the Python block, and the result of the block is returned as a #Pythonx.Object<...>.

Note: The ~PY sigil does not work within standard Mix project code; in applications, you should manage Python globals explicitly via Pythonx.eval/2.

import Pythonx

x = 1

~PY"""
y = 10
result = x + y
"""

result
#=> #Pythonx.Object<11>

The ~PY sigil is a convenience macro for evaluating Python code. It automatically handles globals: any Elixir variables referenced in the Python code are automatically encoded and passed as globals, and any globals assigned in the Python code are defined as Elixir variables.

Warning: This macro evaluates code at compile time. It is intended for dynamic environments like IEx or Livebook. For regular application code, use Pythonx.eval/3 to make dependency management explicit.

import Pythonx

x = 1
~PY"""
y = 10
x + y
"""
# returns 11
# y is now defined as #Pythonx.Object<10>