Install & Compatibility
Where this runs
tested against v0.3.0 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.385s · 18.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.8s · import 0.337s · 19MB
64MB installed
● package 64MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
install
✓ import maturin_import_hook; maturin_import_hook.install()
Demonstrates how to use `maturin-import-hook` to dynamically load a Rust module defined in a `maturin` project. It sets up a minimal Rust project with a `pyproject.toml` and `src/lib.rs`, installs the hook, imports the Rust module, calls a function, and then cleans up. This example assumes `maturin` is already installed in your environment.
import maturin_import_hook
import sys
import os
import shutil
# This hook allows Python to find and load Rust modules
# defined in a maturin project within the current directory
# or a parent directory.
maturin_import_hook.install()
# --- Setup a dummy Rust project for demonstration ---
# In a real project, this setup would already exist.
project_name = "my_rust_module"
project_dir = "temp_rust_project"
module_path = os.path.join(project_dir, "src")
# Clean up any previous run's artifacts
if os.path.exists(project_dir):
shutil.rmtree(project_dir)
os.makedirs(module_path, exist_ok=True)
# Create pyproject.toml
with open(os.path.join(project_dir, "pyproject.toml"), "w") as f:
f.write(f"""
[project]
name = "{project_name}"
version = "0.1.0"
[tool.maturin]
name = "{project_name}"
bindings = "pyo3"
""")
# Create Cargo.toml (maturin can infer some parts, but explicit is clearer for quickstart)
with open(os.path.join(project_dir, "Cargo.toml"), "w") as f:
f.write(f"""
[package]
name = "{project_name}"
version = "0.1.0"
edition = "2021"
[lib]
name = "{project_name}"
crate-type = ["cdylib"]
[dependencies]
pyo3 = {{ version = "0.20", features = ["extension-module"] }}
""")
# Create src/lib.rs with a simple PyO3 function
with open(os.path.join(module_path, "lib.rs"), "w") as f:
f.write("""
use pyo3::prelude::*;
#[pyfunction]
fn greet() -> PyResult<String> {
Ok("Hello from Rust!".to_string())
}
#[pymodule]
fn my_rust_module(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
m.add_function(wrap_pyfunction!(greet, m)?)?;
Ok(())
}
""")
# Change to the project directory so the hook can find pyproject.toml
original_cwd = os.getcwd()
os.chdir(project_dir)
print(f"Attempting to import '{project_name}' from: {os.getcwd()}")
# Now, import the Rust module as if it were a Python module
# The hook will find pyproject.toml and potentially build the module.
try:
import my_rust_module
message = my_rust_module.greet()
print(f"✅ Successfully imported and called Rust module: {message}")
except ImportError as e:
print(f"❌ Failed to import Rust module: {e}", file=sys.stderr)
print("Ensure 'maturin' is installed (pip install maturin) and your Rust project is valid.", file=sys.stderr)
except Exception as e:
print(f"❌ An unexpected error occurred: {e}", file=sys.stderr)
finally:
# Clean up dummy project and restore original cwd
os.chdir(original_cwd)
if os.path.exists(project_dir):
print(f"Cleaning up temporary project directory: {project_dir}")
shutil.rmtree(project_dir)
Errors
Common errors & fixes
ImportError: No module named 'your_rust_module'
The `maturin_import_hook.install()` function was not called, or the `pyproject.toml` and Rust project structure are not correctly set up or discoverable by the hook.
fixEnsure `maturin_import_hook.install()` is called early in your application's lifecycle, and verify that a valid `pyproject.toml` file is in the current working directory or a parent relative to where the script is run.
ModuleNotFoundError: No module named 'maturin'
The `maturin` CLI tool, which `maturin-import-hook` relies on for building and discovery, is not installed in the active Python environment.
fixInstall `maturin` using `pip install maturin` in the same Python environment.
(Rust compiler errors, e.g., 'error[E0425]: cannot find function `some_rust_function` in crate `some_crate`' during import)
The underlying Rust project has compilation issues (e.g., syntax errors, missing dependencies in `Cargo.toml`, incorrect PyO3 bindings). These errors occur when the hook attempts to build the Rust extension.
fixReview the detailed error messages from `cargo build` (which `maturin` wraps) to diagnose and fix issues in your `Cargo.toml` or Rust source code. You can often reproduce these by running `maturin build` manually in your Rust project directory to get clearer output.
Upgrade
Version history
0.3.0latest on PyPI · released Jun 8, 2025
Audit
Dependencies
maturinrequiredRequired for building and locating Rust extensions.