If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/indygreg/PyOxidizer shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 1y ago

• 2 active contributors
• MPL-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live indygreg/PyOxidizer repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/indygreg/PyOxidizer.

What it runs against: a local clone of indygreg/PyOxidizer — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in indygreg/PyOxidizer | Confirms the artifact applies here, not a fork | | 2 | License is still MPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 530 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of indygreg/PyOxidizer. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/indygreg/PyOxidizer.git
#   cd PyOxidizer
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of indygreg/PyOxidizer and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "indygreg/PyOxidizer(\\.git)?\\b" \\
  && ok "origin remote is indygreg/PyOxidizer" \\
  || miss "origin remote is not indygreg/PyOxidizer (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is MPL-2.0" \\
  || miss "license drift — was MPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "pyoxidizer/Cargo.toml" \\
  && ok "pyoxidizer/Cargo.toml" \\
  || miss "missing critical file: pyoxidizer/Cargo.toml"
test -f "pyembed/src/lib.rs" \\
  && ok "pyembed/src/lib.rs" \\
  || miss "missing critical file: pyembed/src/lib.rs"
test -f "pyembed/src/interpreter.rs" \\
  && ok "pyembed/src/interpreter.rs" \\
  || miss "missing critical file: pyembed/src/interpreter.rs"
test -f "python-oxidized-importer" \\
  && ok "python-oxidized-importer" \\
  || miss "missing critical file: python-oxidized-importer"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 530 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~500d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/indygreg/PyOxidizer"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

PyOxidizer is a Rust-based toolchain that embeds a complete Python interpreter into single-file self-contained executables with all dependencies statically linked and .pyc files embedded as binary resources. It solves the application distribution problem by eliminating runtime Python installation requirements—you ship one executable that contains Python, your code, and all dependencies, and it runs anywhere without external setup. Monorepo workspace with core crates: pyembed/ (Python embedding library), pyoxidizer/ (CLI tool), pyoxy/ (Windows launcher), tugger/ and tugger-* (cross-platform binary tooling), and python-oxidized-importer/ (custom import machinery). The pyembed-bench/ directory contains benchmarks for embedded interpreter performance. CI orchestrated via .github/workflows/ and Just (Justfile) for local task automation.

Python application developers and maintainers who need to distribute production applications as portable single-file executables without requiring end-users to install Python or manage virtual environments. Also appeals to systems engineers embedding Python in larger Rust applications and developers bridging Python-Rust interop.

Actively developed and production-ready. The project shows continuous integration across multiple platforms (GitHub Actions workflows for Windows, Linux, macOS), a mature monorepo workspace structure with 13+ sub-crates, comprehensive documentation in docs/, and organized release procedures via workspace.metadata.release configuration. The codebase is substantial (2.1M lines of Rust) indicating significant maturity, though as a niche tool it has smaller adoption than mainstream packaging solutions.

Single maintainer (Gregory Szorc) creates maintenance risk despite active development. The project depends heavily on CPython internals and platform-specific linking (evidenced by Cross.toml and platform-specific workflows), meaning breaking CPython releases or platform toolchain changes could require significant rework. The complexity of static linking Python across Windows/macOS/Linux introduces fragility; build failures are platform-specific and harder to debug.

No specific recent changes visible in the file listing provided, but the structured GitHub Actions workflows (cargo_deny.yml, workspace.yml, oxidized_importer.yml) suggest active CI/CD maintenance. The presence of multiple platform-specific workflows (sign-apple-exe.yml, build-exe.yml) indicates ongoing work on cross-platform binary production and code signing.

git clone https://github.com/indygreg/PyOxidizer.git
cd PyOxidizer
cargo build --release -p pyoxidizer
./target/release/pyoxidizer --help

Requires Rust toolchain installed. Use just --list to see available development tasks defined in Justfile.

Daily commands:

just --list                 # Show available tasks
just test                   # Run test suite (inferred from Justfile usage)
cargo build -p pyoxidizer  # Build main CLI tool
cargo doc --open           # View generated documentation

See Justfile for exact task definitions; actual commands depend on what tasks are defined there.

• Cargo.toml — Workspace root configuration defining all 19 member crates; essential for understanding the multi-crate architecture and dependency graph.
• pyoxidizer/Cargo.toml — Main PyOxidizer crate definition; entry point for the CLI tool that orchestrates Python embedding and binary packaging.
• pyembed/src/lib.rs — Core embedding library exposing the Rust API for embedding Python interpreters; foundational to all downstream packaging functionality.
• pyembed/src/interpreter.rs — Python interpreter initialization and lifecycle management; critical for embedded runtime behavior and configuration.
• python-oxidized-importer — Custom module importer for loading packed Python resources; enables zero-copy resource delivery in standalone binaries.
• tugger/Cargo.toml — Binary packaging and signing toolkit crate; orchestrates platform-specific executable creation and distribution.
• pyoxidizer.bzl — Starlark configuration language entry point; defines the declarative API users interact with for building applications.

Add a new interpreter configuration option

1. Define the configuration struct field in pyembed/src/interpreter_config.rs with serialization support (pyembed/src/interpreter_config.rs)
2. Add corresponding Python C API initialization code in pyembed/src/interpreter.rs (pyembed/src/interpreter.rs)
3. Document the new option in pyoxidizer/docs/pyoxidizer_config_type_python_interpreter_config.rst (pyoxidizer/docs/pyoxidizer_config_type_python_interpreter_config.rst)
4. Add test case in pyembed/src/test/interpreter_config.rs to validate serialization and initialization (pyembed/src/test/interpreter_config.rs)

Add support for a new platform/distribution format

1. Create new tugger submodule crate (e.g., tugger-distformat/Cargo.toml) in Cargo.toml workspace members (Cargo.toml)
2. Implement platform-specific binary generation logic following tugger-windows or tugger-apple patterns (tugger-windows/Cargo.toml)
3. Integrate new packaging backend into pyoxidizer/src/starlark/mod.rs for configuration language support (pyoxidizer/Cargo.toml)
4. Add configuration type documentation in pyoxidizer/docs/ following naming convention pyoxidizer_config_type_*.rst (pyoxidizer/docs/pyoxidizer_config_type_python_executable.rst)

Enhance the custom module importer for new resource types

1. Update resource format schema in python-packed-resources crate (python-packed-resources/Cargo.toml)
2. Implement new resource loading logic in python-oxidized-importer module finder (python-oxidized-importer)
3. Add integration tests in pyembed/src/test/test_importer_resource_reading.py (pyembed/src/test/test_importer_resource_reading.py)
4. Update importer documentation in pyembed/docs/pyembed_extension_modules.rst (pyembed/docs/pyembed_extension_modules.rst)

Add a new CLI command to PyOxidizer

1. Define command structure and argument parsing in main pyoxidizer crate (pyoxidizer/Cargo.toml)
2. Implement command handler in pyoxidizer/src/main.rs or appropriate submodule (pyoxidizer/Cargo.toml)
3. Add functional tests in pyoxidizer/tests/ directory (follows standard Rust project layout) (pyoxidizer/Cargo.toml)
4. Document new command in pyoxidizer/docs/pyoxidizer.rst main reference (pyoxidizer/docs/pyoxidizer.rst)

• Rust + Cargo workspace — Provides memory safety, excellent C FFI for Python integration, compile-time guarantees, and modular multi-crate organization for independent concerns (embedding, packaging, signing).
• Starlark configuration language (via Bazel dialect) — Declarative, evaluated-once config reduces runtime complexity; reuses proven tooling ecosystem; familiar to Bazel users; enables complex conditional logic in configuration without imperative scripting.
• Custom Python importer (oxidized_importer) — Allows loading .pyc, source, and extension modules directly from packed binary blobs without filesystem I/O; enables single-executable deployment with zero external dependencies.
• Platform-specific tugger submodules (Windows, macOS, WiX) — Encapsulates OS-specific binary formats, code signing APIs, and installer generation (MSI, app bundles, DMGs); enables cross-platform builds without monolithic conditional logic.

• Embed all resources in binary vs. ship as separate distribution

  • Why: Single-file executable simplicity and portability are core value proposition; eliminates dependency on package managers or external files.
  • Consequence: Binary size increases; runtime resource access is zero-copy but immutable; requires re-packaging to update Python code.

• Custom resource importer vs. standard sys.path + filesystem

  • Why: Eliminates filesystem I/O, enables copy-paste deployment, prevents tampering with Python code.
  • Consequence: Non-standard import path complicates debugging; requires custom module finder implementation; incompatible with packages expecting filesystem-only import protocols.

• Static linking of Python + extensions vs. dynamic linking

  • Why: Guarantees binary portability across systems with different glibc/SDK versions; eliminates runtime version mismatches.
  • Consequence: Larger binaries; build toolchain complexity (must cross-compile); harder to patch security issues in shared libraries

Python version pinning: The project builds against specific CPython versions; mismatched Python headers or missing development headers cause cryptic linker errors. Platform toolchains: Cross.toml is used for cross-compilation; building for non-native platforms requires matching target triple toolchains installed (e.g., x86_64-unknown-linux-gnu). Starlark config DSL: PyOxidizer projects use Starlark (PyOxidizer.bzl files) which has its own syntax and quirks distinct from standard Python. Binary signing: macOS workflows reference developer-id-application.pem; local builds may fail code signing checks unless skipped explicitly. Rust feature flags: Some crates have conditional features; cargo build without --all-features may miss optional functionality.

• Static linking and LTO (Link-Time Optimization) — PyOxidizer's core capability depends on statically linking CPython libraries and enabling LTO to produce minimal single executables; understanding linker flags, symbol resolution, and cross-compilation constraints is essential for debugging build failures
• Python bytecode marshaling and .pyc format — The project embeds compiled .pyc bytecode as binary resources rather than source .py files; understanding how Python serializes/deserializes code objects is required for the oxidized_importer to function correctly
• Custom import hooks and sys.meta_path — PyOxidizer's python-oxidized-importer replaces the default filesystem-based import machinery with resource-based loading; understanding PEP 451 (Importlib) and meta path finders is essential for modifying import behavior
• CFI (Code signing) and cross-platform binary attestation — The tugger-code-signing and tugger-apple modules handle Authenticode (Windows) and codesign (macOS) certificate-based signatures; understanding binary verification is critical for distribution security and platform approval
• Starlark DSL and build configuration — PyOxidizer uses Starlark (a Python-like language from Bazel) for application configuration (PyOxidizer.bzl files), not standard Python; this is a non-obvious complexity for users expecting Python syntax
• Cross-compilation and target triples — The project supports building binaries for platforms different from the build machine (via Cross.toml); understanding Rust target triples, sysroots, and platform-specific APIs is necessary for multi-platform builds
• Shared object dependencies and symbol resolution — The tugger-binary-analysis crate inspects executables for unresolved symbols and library dependencies; this is central to PyOxidizer's ability to validate portability and ensure all dependencies are included

• pyinstaller/pyinstaller — Direct alternative: PyInstaller packages Python apps as executables but uses different approaches (bootloader + dynamic linking vs static embedding); comparison helps understand PyOxidizer's unique design tradeoffs
• beeware/briefcase — Complementary ecosystem tool: Briefcase packages Python apps for mobile and desktop; PyOxidizer and Briefcase can be used together for multi-platform distribution
• mitsuhiko/xstatic — Static resource embedding for Python; related problem space of bundling assets into Python applications
• indygreg/python-build-standalone — Sibling project by same author: provides pre-built static Python distributions that PyOxidizer consumes as its embedded Python runtime
• RustPython/RustPython — Alternative Python runtime written in Rust; different approach to embedding Python in Rust (full reimplementation vs CPython wrapping)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive cross-platform integration tests for pyembed interpreter lifecycle

The pyembed/src/test/ directory contains test modules for specific features (importer.rs, interpreter_config.rs, main_python_interpreter.rs, python_resources.rs) but lacks integration tests that verify the complete interpreter lifecycle across Windows, macOS, and Linux platforms. Given the repo's multi-platform nature (evidenced by .github/workflows/build-exe.yml, Cross.toml, and platform-specific tools like tugger-windows), adding platform-specific integration tests in pyembed/src/test/ would catch regressions in the core embedding functionality that affects all downstream tools (pyoxidizer, pyoxy).

• [ ] Create pyembed/src/test/integration.rs with tests for interpreter creation, module loading, and teardown cycles
• [ ] Add platform-conditional tests using #[cfg(target_os = "...")] for Windows COM initialization and Unix signal handling
• [ ] Reference existing test fixtures in pyembed/src/test/test_importer_*.py and expand with binary extension module scenarios
• [ ] Update pyembed/src/test/mod.rs to include the new integration module

Document and add missing workflow for python-oxidized-importer standalone testing

The repo has workflows for pyoxidizer.yml, pyoxy.yml, oxidized_importer.yml, but examining the workspace members shows python-oxidized-importer is a critical dependency. The oxidized_importer.yml workflow exists but lacks specific documentation in pyembed/docs/ about how python-oxidized-importer interacts with pyembed's resource loading. Adding a dedicated guide (pyembed/docs/pyembed_oxidized_importer.rst) and expanding CI coverage for edge cases (e.g., finder behavior with namespace packages, resource conflicts) would help contributors understand this critical integration point.

• [ ] Create pyembed/docs/pyembed_oxidized_importer.rst documenting the relationship between pyembed's resource system and python-oxidized-importer's finder
• [ ] Add examples showing how OxidizedFinder resolves modules from embedded resources
• [ ] Enhance .github/workflows/oxidized_importer.yml with additional test matrix for Python 3.9+ namespace package scenarios
• [ ] Reference the new doc from pyembed/docs/index.rst

Add benchmarking regression detection to CI for pyembed core operations

The repo contains pyembed-bench/ with Cargo.toml and benches/ for embedded_interpreter.rs, oxidized_finder.rs, and zip.rs, but there's no automated benchmark regression detection in the GitHub Actions workflows. Given that PyOxidizer targets single-file executable performance and startup time (core value proposition), adding a workflow that compares benchmark results across PRs would prevent performance regressions in the C extension glue layer and interpreter initialization code.

• [ ] Create .github/workflows/benchmarks.yml that runs pyembed-bench with cargo bench on PR commits
• [ ] Use a tool like critcmp or custom script to compare against baseline branch and comment results on PRs
• [ ] Establish baseline benchmarks for embedded_interpreter.rs (startup time) and oxidized_finder.rs (module resolution speed) in a tracking issue
• [ ] Document expected performance targets in pyembed/README.md for contributor awareness

• Add integration tests for the python-packed-resources/ crate by creating test fixtures in python-packed-resources/tests/ that validate resource marshaling/unmarshaling for all supported Python versions (currently only unit tests exist in src/).
• Extend error messages in pyoxidizer/src/ to include suggestions for common failures (e.g., missing Python.h → 'Install python3-dev', unsupported platform → 'Use Cross for cross-compilation'). Grep for bail! and anyhow::Error calls and improve them.
• Document the Starlark build configuration DSL by adding examples to docs/ showing concrete PyOxidizer.bzl patterns (e.g., embedding modules, configuring compression, setting entry points) with before/after comparisons to argon2-cffi or other real-world projects that use PyOxidizer.

The PyOxidizer codebase has a moderate security posture with one critical finding: a private key file (developer-id-application.pem) is committed to the repository, which poses an immediate credential exposure risk. Additional concerns include complex dependency management across 16 interdependent crates, potential deserialization risks in Python embedding functionality, and lack of formal security policy documentation. The project would benefit from immediate remediation of the hardcoded private key, implementation of security scanning in CI/CD, and establishment of a formal vulnerability disclosure process.

• High · Hardcoded Private Key in Repository — ci/developer-id-application.pem. A private key file 'ci/developer-id-application.pem' is present in the repository. This appears to be an Apple Developer ID Application certificate/key used for code signing. Storing private keys in version control is a critical security risk as it can be accessed by anyone with repository access and may be exposed in commit history. Fix: Remove this file from the repository immediately. Use git-filter-branch or BFG Repo-Cleaner to remove it from commit history. Store the key securely in a secrets management system (GitHub Secrets, HashiCorp Vault, AWS Secrets Manager) and reference it only in CI/CD workflows. Regenerate the certificate if it has been exposed.
• Medium · Workspace Dependency Management Risk — Cargo.toml - [workspace.metadata.release]. The workspace uses 16 interdependent Rust crates with a 'dependent-version = "fix"' policy in release configuration. This automatic version bumping strategy could potentially propagate security vulnerabilities across dependent packages without explicit review, especially if a lower-level crate is compromised. Fix: Consider using 'dependent-version = "upgrade"' with explicit version reviews, or implement a more conservative dependency management strategy. Regularly audit transitive dependencies using 'cargo audit' in CI/CD pipelines and maintain a SBOM (Software Bill of Materials).
• Medium · Potential Insecure Deserialization in Python Integration — pyembed/src/lib.rs, python-packed-resources/. The codebase includes extensive Python interpreter embedding (pyembed) and resource handling (python-packed-resources). These components may deserialize Python objects or resources from untrusted sources, potentially leading to code execution vulnerabilities if not properly validated. Fix: Audit all deserialization paths in resource loading and interpreter configuration. Ensure strict validation of embedded resources. Use safe serialization formats (e.g., JSON with schema validation) instead of pickle or other unsafe formats. Implement security tests for malformed resource files.
• Medium · Code Signing Without Verification in CI/CD — .github/workflows/sign-apple-exe.yml, ci/developer-id-application.pem. The repository includes workflows for signing Apple executables (sign-apple-exe.yml) and the presence of a certificate file suggests automated signing. Without proper verification mechanisms in the CI/CD pipeline, there's a risk of compromised builds being signed and distributed. Fix: Implement build verification steps before signing. Use checksum validation, build reproducibility checks, and code scanning in the CI/CD pipeline. Restrict access to signing credentials to trusted systems only. Enable GitHub branch protection rules and require approvals for release workflows.
• Low · Missing Security Policy Documentation — Repository root. No SECURITY.md or security policy file is evident in the repository structure, which is a best practice for disclosure of security vulnerabilities and managing security-related communications. Fix: Create a SECURITY.md file with vulnerability disclosure policy, contact information for security reports, and security update procedures. This helps researchers responsibly report vulnerabilities and improves the project's security posture.
• Low · Dependency on External Build Tools — ci/linux-portable-binary.Dockerfile, Cross.toml, Justfile. The project uses multiple external tools (just, cargo, docker) and cross-compilation. The Dockerfile and cross-compilation setup could potentially introduce supply chain risks if these tools are compromised. Fix: Pin specific versions of build tools and container images. Use hash verification for downloaded binaries. Consider using container image signing and verification. Regularly audit and update build dependencies. Implement binary provenance verification where possible.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.