py2pyd

🚀 A high-performance Rust-based tool to compile Python modules to extension files (.pyd on Windows, .so on Linux/macOS) with zero-dependency executables.

✨ Features Docker-powered CI/CD with 5-10x faster builds and truly portable executables that run anywhere without installation.

Note: This project is under active development. While core functionality is stable, APIs may evolve. We provide zero-dependency executables for maximum portability.

Overview

py2pyd is a high-performance, Rust-based command-line tool that compiles Python (.py) files to Python extension modules (.pyd on Windows, .so on Linux/macOS). Built with modern DevOps practices, it features Docker-powered CI/CD for lightning-fast builds and produces zero-dependency executables for maximum portability.

🎯 Key Highlights

• 🚀 Zero-Dependency Executables: Download and run immediately - no installation required
• ⚡ Lightning Fast: Docker-powered builds with 5-10x performance improvements
• 🌍 Universal Compatibility: Static binaries work on any Windows system or Linux distribution
• 🔒 Enterprise Ready: Enhanced security scanning and strict code quality standards
• 🐳 Modern CI/CD: Docker-based pipeline with specialized images for different tasks

Features (Planned)

• Compile single Python files or entire directories to Python extension modules (.pyd on Windows, .so on Linux/macOS)

• Support for multiple Python interpreter discovery methods:

  • Default PATH lookup
  • uv integration with version selection (--uv-python 3.10)
  • Explicit interpreter path specification (--python-path)

• Batch processing with recursive directory support

• Optimization level control

• Comprehensive logging and error reporting

Installation

🚀 Download Zero-Dependency Executables

Download the latest release from the Releases page.

Windows (Zero Dependencies)

• 64-bit: py2pyd-x86_64-pc-windows-gnu.zip - Runs on any Windows system
• 32-bit: py2pyd-i686-pc-windows-gnu.zip - Compatible with older systems

Linux (Static Binaries)

• 64-bit: py2pyd-x86_64-unknown-linux-musl.tar.gz - Works on any Linux distribution
• ARM64: py2pyd-aarch64-unknown-linux-musl.tar.gz - For ARM64 Linux systems

macOS

• Intel: py2pyd-x86_64-apple-darwin.tar.gz
• Apple Silicon: py2pyd-aarch64-apple-darwin.tar.gz

💡 Tip: Windows and Linux musl builds are completely self-contained with zero dependencies. Just download, extract, and run!

Build from Source

git clone https://github.com/loonghao/py2pyd.git
cd py2pyd
cargo build --release

The binary will be available at target/release/py2pyd (or py2pyd.exe on Windows).

Cross-Compilation Support

This project includes enhanced cross-compilation support based on rust-actions-toolkit best practices:

• Windows targets: Properly configured for x86_64-pc-windows-gnu and i686-pc-windows-gnu
• Memory allocator compatibility: Resolved libmimalloc-sys build errors in cross-compilation environments
• Enhanced toolchain: Pre-configured Cross.toml with proper environment variables

To test cross-compilation locally:

# Install cross-compilation tool
cargo install cross

# Test Windows targets
cross build --target x86_64-pc-windows-gnu --release
cross build --target i686-pc-windows-gnu --release

For troubleshooting cross-compilation issues, see the rust-actions-toolkit documentation.

Usage

# Basic usage (uses Python from PATH)
py2pyd -i input.py -o output.pyd

# Using uv with specific Python version
py2pyd --uv-python 3.10 -i input.py -o output.pyd

# Using explicit Python interpreter path
py2pyd --python-path C:/Python310/python.exe -i input.py -o output.pyd

# Batch processing
py2pyd --uv-python 3.10 -i src/ -o build/ --recursive

Requirements

• Operating system:
  • Windows (primary target)
  • Linux and macOS (experimental support)
• Compatible C/C++ compiler for the target Python version:
  • Windows:
    • MSVC (Recommended): Install Visual Studio Build Tools from here
    • MinGW-w64 (Alternative): Install from here
  • Linux: GCC (install via sudo apt-get install build-essential on Debian/Ubuntu)
  • macOS: Xcode Command Line Tools (install via xcode-select --install)
• Python interpreter (if not using embedded mode)

The tool will automatically check for required build tools and provide installation instructions if they are missing.

Testing

py2pyd includes comprehensive tests, including integration tests that download and compile real Python packages from PyPI.

Quick Tests

# Run unit tests only
cargo test

Integration Tests

# Run all tests including integration tests (requires internet and build tools)
cargo test -- --ignored

# Test compiling a simple Python module
cargo test test_compile_simple_python_module -- --ignored

# Test downloading and compiling a real PyPI package
cargo test test_download_six_package -- --ignored

For detailed testing information, see TESTING_GUIDE.md.

🐳 Docker-Powered Development

This project leverages cutting-edge Docker technology for development and CI/CD:

Performance Improvements

Docker Images Used

• ghcr.io/loonghao/rust-toolkit:base - General CI/CD operations
• ghcr.io/loonghao/rust-toolkit:cross-compile - Zero-dependency builds
• ghcr.io/loonghao/rust-toolkit:security-audit - Enhanced security scanning

Zero-Dependency Builds

Our release pipeline produces truly portable executables:

• Windows: No DLL dependencies, runs on any Windows system
• Linux: Static musl binaries work on any distribution
• Single File: Download and run immediately

This ensures maximum compatibility and ease of distribution.

TODO List

• Implement flexible Python interpreter discovery
  • PATH-based discovery
  • uv integration with version selection
  • Explicit path specification
• Improve MSVC compiler detection and integration
  • Auto-detection of installed MSVC
  • Clear error messages and installation guidance
  • Investigate minimal MSVC toolchain options
• Enhance compilation process
  • Optimize Cython usage
  • Improve error handling and reporting
  • Add support for compilation configuration
• Add comprehensive testing
  • Unit tests for different Python versions
  • Integration tests for various compilation scenarios
  • CI/CD pipeline setup
• Improve documentation
  • Detailed usage examples
  • Troubleshooting guide
  • API documentation
• Future enhancements
  • Investigate embedded Python interpreter option
  • Support for additional platforms (Linux, macOS)
  • Performance optimizations

Release Process

This project uses Semantic Release with automated CI/CD. Releases are automatically triggered based on Conventional Commits:

Automatic Version Bumping

How to Release

Simply use conventional commit messages when pushing to main:

# Feature addition (minor version bump)
git commit -m "feat: add support for Python 3.12"

# Bug fix (patch version bump)
git commit -m "fix: handle edge case in file parsing"

# Breaking change (major version bump)
git commit -m "feat!: redesign command-line interface

BREAKING CHANGE: The --input flag is now required"

The CI system will automatically:

1. Analyze commit messages to determine version bump
2. Update version in Cargo.toml
3. Build binaries for all supported platforms
4. Create Git tag and GitHub release
5. Upload artifacts with generated release notes

For detailed information, see docs/VERSIONING.md.

Contributing

Contributions are welcome! Please follow these guidelines:

Commit Message Format

This project uses Conventional Commits. Please format your commit messages as:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code
• refactor: A code change that neither fixes a bug nor adds a feature
• perf: A code change that improves performance
• test: Adding missing tests or correcting existing tests
• chore: Changes to the build process or auxiliary tools

Examples:

feat(parser): add support for async functions
fix(compiler): resolve segmentation fault on Windows
docs(readme): add installation instructions
refactor(core): simplify error handling logic

Pull Request Process

1. Fork the repository
2. Create a feature branch
3. Make your changes using conventional commits
4. Submit a pull request

Please feel free to submit a Pull Request!

License

This project is licensed under the MIT License - see the LICENSE file for details.