Documentation
Technical documentation for installing, configuring, and running the Pyvorin compiler.
Token Refresh
Licence device tokens can be refreshed without repeating the full activation flow. pyvorin auth refresh This contacts the Portal and exchanges the current token for a fresh one. Refresh is automatic in most cases, but you can run it manually if you see authentication errors.
Updated 1 month ago
Auth Status
Check your current authentication state at any time. pyvorin auth status The output shows your account email, device identifier, licence key label, expiry, and device limit usage. Use this output when opening support tickets.
Updated 1 month ago
Revoking Devices
Revoking a device removes its access to your licence. This is useful when you replace hardware or deactivate a CI runner. Open the Licences page in the Portal.Select the licence key.Find the device in the active devices list.Click Revoke. The device token becomes invalid immediately. The CLI on that device must re-authenticate before it can compile again.
Updated 1 month ago
Debugging
Pyvorin provides several tools for diagnosing problems without exposing secrets or source code. pyvorin doctorpyvorin doctorChecks Python version and platform support, network reachability to the Portal, licence and device token validity, and configuration file syntax. Compile logspyvorin compile app.py --verboseVerbose mode prints per-module compilation status, fallback reasons, and timing. Logs are stored locally and are not uploaded unless telemetry is enabled. Reporting bugspyvorin report-bug --title "Unexpected fallback" --logsThis creates a support ticket. By default, source code is not attached, command text is redacted, and stack traces are included.
Updated 1 month ago
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
Performance Guide
Pyvorin performance depends on how much of your program compiles to native code, the build mode, and the workload. General guidanceMeasure before optimizing. Use pyvorin compile app.py --report to find native coverage.Focus refactoring on hot loops and functions with high call counts.Use performance mode only after balanced mode produces correct results. Parallel compilationpyvorin compile app.py --threads=8Increase threads for large projects. The default is usually adequate for small scripts. Realistic expectationsPyvorin is most effective for CPU-bound Python code. I/O-bound programs may see smaller gains because network or disk latency dominates runtime.
Updated 1 month ago
Parallel Compilation
Pyvorin can compile independent modules in parallel to reduce build time. pyvorin compile app.py --threads=8 The optimal thread count depends on your CPU and project size. For small projects, more threads may not help. For large projects, values up to the number of physical cores are a reasonable starting point. Set a default in pyvorin.toml under build.threads.
Updated 1 month ago
Measuring Speedup
Measure speedup by comparing the native build against the same code running under CPython. time python app.py time ./build/app Use representative inputs and warm up caches. Reported compile metrics in the Portal show native coverage and estimated speedup over time, but real-world results depend on your workload.
Updated 1 month ago
CPU-Bound Workloads
CPU-bound programs are the most likely to benefit from native compilation. Examples include numerical loops, data transformation, parsing, and simulation. Native code removes interpreter overhead for supported constructs, which can reduce runtime significantly when the same hot path executes many times. Use performance mode after validating correctness to maximize throughput.
Updated 1 month ago
I/O-Bound Workloads
I/O-bound programs spend most of their time waiting for network, disk, or external services. Native compilation may reduce startup time and parsing overhead, but it cannot remove network latency or disk waits. Programs dominated by I/O are less likely to show large speedups. Measure end-to-end performance rather than relying on native coverage percentage alone.
Updated 1 month ago