skills.rest
illumination-k
illumination-kCOMMUNITY
Explore all skills by this author →
GitHub

maturin-debugger

Diagnose PyO3 build failures and verify #[pymodule] registrations for maturin projects.

1|Updated Jun 24, 2025
Search Tags:#debugging#python#rust#pyo3#maturin#build issues#bindings
One-click install
npx skills add https://github.com/illumination-k/pubmed-client --skill maturin-debugger
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: maturin-debugger
Source: https://github.com/illumination-k/pubmed-client/tree/main/.claude/skills/maturin-debugger
Command: npx skills add https://github.com/illumination-k/pubmed-client --skill maturin-debugger

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Maturin and PyO3 development often leads to cryptic build issues, especially when new Rust methods compile but don't appear in Python. This Skill cuts through the complexity, automating diagnosis and providing precise fixes for common problems like caching conflicts, module registration errors, and type stub generation issues, saving developers hours of frustrating debugging.

Core Features & Use Cases:

  • UV + Maturin Conflict Resolution: Automatically detects and guides fixes for the notorious uv package manager conflict that prevents new PyO3 methods from loading.
  • Maturin Caching Workaround: Provides a reliable rebuild sequence to bypass maturin develop caching issues, ensuring your latest Rust code is always reflected in Python.
  • Module Registration Verification: Scans your Rust source to confirm all #[pyclass] types are correctly registered in #[pymodule], preventing silent export failures.
  • Use Case: You've added a new method to your Rust PyO3 class, it compiles, but Python's dir() doesn't show it. Activate this Skill to quickly identify if it's a uv conflict, a maturin caching bug, or a missing module registration, and get step-by-step instructions to fix it.

Quick Start: I'm having trouble with my PyO3 module pubmed_client. New methods aren't showing up. Can you help me debug it, checking for Client, PubMedClient, and SearchQuery classes?

Frequently Asked Questions about maturin-debugger

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why aren't my new PyO3 methods showing up in Python after compiling?▼

New Rust methods compiled with PyO3 often fail to appear in Python due to UV + maturin conflicts, maturin caching issues, or missing module registration. This Skill diagnoses which problem you have and provides step-by-step fixes, checking UV configuration, clearing caches, and verifying #[pyclass] types are registered in #[pymodule].

How do I fix maturin build issues when my PyO3 bindings fail to import?▼

Maturin PyO3 modules can fail to import despite successful Rust compilation due to caching, registration, or UV conflicts. This Skill automates diagnosis by scanning your Rust source for unregistered #[pyclass] declarations, detecting UV package manager conflicts, and executing reliable rebuild sequences to resolve the underlying issue.

What's the best way to debug PyO3 module registration problems?▼

PyO3 module registration errors occur when #[pyclass] types aren't properly exported in #[pymodule]. This Skill verifies all Rust classes are correctly registered, detects silent export failures, generates type stubs for Python verification, and provides targeted fixes without manual source inspection.

Does maturin work with the UV package manager for PyO3 development?▼

The UV package manager has known conflicts with maturin that prevent new PyO3 methods from loading into Python despite successful compilation. This Skill detects UV + maturin incompatibilities and guides you through resolving them so your latest Rust code appears in Python.

How do I clear maturin caching issues when my Rust changes don't reflect in Python?▼

Maturin develop caching can obscure correct behavior, hiding newly compiled Rust code from Python imports. This Skill provides a reliable rebuild sequence that bypasses maturin caching issues, ensuring your latest changes are reflected and verified in Python without manual workarounds.

When should I verify my PyO3 module registration before troubleshooting build errors?▼

Verify module registration early when new methods compile but don't appear in Python, as missing #[pyclass] registration in #[pymodule] causes silent export failures. This Skill scans your Rust source automatically, confirms registration correctness, and prevents hours of debugging misdiagnosed caching or UV conflicts.

Related Skills

Explore More Software Engineering Skills→
drdave-flexnetosdrdave-flexnetos

rust-tooling

Build PyO3 Rust extensions with maturin and sqlx-verified SQL access.

Community
Advanced
agentglassagentglass
1

python-bindings

Create Python bindings for Rust code using PyO3 and Maturin.

Official
Advanced
FlexNetOSFlexNetOS

rust-tooling

Bridge Rust and Python with PyO3 bindings for ROS2 development.

Community
Advanced
Just-itJust-it
33

ascend-call-generation

Generate Ascend C projects and operator invocation code from functional PyTorch code.

Community
Intermediate