Documentation
Technical documentation for installing, configuring, and running the Pyvorin compiler.
Project Configuration
Pyvorin reads project settings from pyvorin.toml in the project root. If that file is missing, it falls back to [tool.pyvorin] inside pyproject.toml. Example pyvorin.toml[project] name = "my-app" entry = "app.py" output_dir = "./build" python_version = "3.11" [build] mode = "balanced" threads = 4 optimize = true [native] extensions = ["numpy", "pydantic"] exclude = ["tests", "docs"] [fallback] allow = true log_reasons = true [telemetry] enabled = true redact_commands = true Configuration keysproject.entry — main entry point file.project.output_dir — directory for build artifacts.build.mode — safe, balanced, performance, or edge.native.extensions — third-party packages allowed in the native build.fallback.allow — whether to permit CPython fallback.telemetry.enabled — send compile and error events to the Portal. Per-command overridespyvorin compile app.py --mode=performance --threads=8
Updated 1 month ago
Native Execution
Native execution runs compiled machine code produced by Pyvorin instead of interpreting Python bytecode with CPython. Native execution applies to code paths that Pyvorin was able to compile. The compiler verifies type consistency, control flow, and memory semantics before emitting native instructions. If any check fails, the construct is marked for fallback. Maximizing native coverageUse explicit types.Prefer standard library calls over dynamic dispatch.Avoid exec, eval, and runtime code generation.Declare third-party extensions in native.extensions. Native execution is not guaranteed for every program. Pyvorin prioritizes correctness: if it cannot prove a construct is safe to compile, it falls back to CPython.
Updated 1 month ago
Fallbacks
A fallback occurs when Pyvorin cannot compile a Python construct to native code and instead runs it through CPython. Fallbacks keep your program correct and runnable. Common fallback reasonsDynamic type changes the compiler cannot track.Unsupported builtin or stdlib function.Runtime import through __import__ or a dynamic path.Use of exec or eval.C extension ABI dependencies. Inspecting fallbackspyvorin compile app.py --report pyvorin fallback-summary Fallbacks are expected behaviour. They do not indicate a bug. A program with fallbacks still benefits from the parts that compiled natively.
Updated 1 month ago
pyvorin.toml Reference
The pyvorin.toml file controls how Pyvorin builds your project. Sections[project] — name, entry, output directory, Python version.[build] — mode, threads, optimization, stripping.[native] — allowed extensions and excluded paths.[fallback] — fallback policy and logging.[telemetry] — event transmission and redaction. Unknown keys are ignored with a warning. Use pyvorin doctor to validate your configuration.
Updated 1 month ago
Build Modes
Pyvorin offers several build modes that trade compatibility against optimization. ModeDescriptionBest forsafeMaximum compatibility; more fallbacks, fewer optimizations.Correctness-critical code and first deployment.balancedDefault. Moderate optimization with clear fallback reporting.Most applications.performanceAggressive optimization; smaller binary, faster runtime.CPU-bound workloads that compile cleanly.edgeTargets the Pyvorin Edge runtime and SDK.Edge deployments through the separate Edge SDK. Start with balanced or safe, then move to performance after you have validated correctness.
Updated 1 month ago
Telemetry Settings
Telemetry sends compile and error events to the Portal so you can track usage and diagnose problems. By default, telemetry is enabled and command text is redacted to a SHA-256 hash. You can change this in pyvorin.toml: [telemetry] enabled = true redact_commands = true Source code is not uploaded. MAC addresses are hashed, and IP addresses are retained with limits. Disable telemetry if your organisation requires it, but note that support diagnostics may be harder without event history.
Updated 1 month ago
Environment Variables
Several environment variables affect CLI behaviour. PYVORIN_CONFIG_DIR — directory for tokens and settings.PYVORIN_LOG_LEVEL — verbosity of CLI output.HTTP_PROXY / HTTPS_PROXY — proxy settings for Portal requests.PYVORIN_NO_TELEMETRY — disables telemetry when set to 1. Environment variables override configuration file values where supported.
Updated 1 month ago