Pyvorin Quick Start — Install, Activate, Benchmark

From a bare machine to a measured benchmark of your own Python function takes about ten minutes with Pyvorin Native. You install one package, activate a licence with a single command, and run a benchmark that compiles your code to native machine code on your own hardware. No source code leaves the machine at any point. This page walks through the whole path using commands we ran ourselves against the installed 1.0.9 build.

One thing up front, because honesty is cheaper than a support ticket: Pyvorin Native is a local compiler, not a remote service. Everything on this page runs on your machine. The only network call involved in activation is a single licence check.

What you need

The requirements are short and non-negotiable:

Python 3.11 or newer. The package metadata declares Requires-Python >=3.11, with classifiers for 3.11 and 3.12.
pip.
Linux x86-64 for the prebuilt binary wheel. The shipped wheel for 1.0.9 is built for CPython 3.12 on linux x86_64, so on other platforms your mileage is unverified — treat anything else as untested until a wheel exists for it.

Check your Python version first:

python --version

If that prints 3.10 or older, install a newer Python before continuing. The package will refuse to install otherwise, which is the correct behaviour but not a helpful error message at 5pm.

Once installed, the product CLI's environment check gives you a one-screen health summary:

python -m pyvorin doctor

It verifies the Python version, llvmlite, a working C compiler, the runtime libraries shipped with the package, NumPy, AVX2 support, available memory and disk, and the cache directory. Run it after every install and after every platform migration; it catches the boring failures — a missing compiler, a wheel for the wrong platform, a read-only cache directory — before they surface as cryptic compile errors inside your application. The warnings it prints are advisory (an uninstalled polars or pandas, say); the failures are the ones to fix before continuing.

Install the package

pip install pyvorin-native

The distribution is called pyvorin-native; the import package is pyvorin. Verify the install landed:

pip show pyvorin-native

You should see version 1.0.9 and a dependency list of pydantic, llvmlite, numpy, msgpack and pynacl. Then confirm the import works:

python -c "import pyvorin; print(pyvorin.__version__)"

A note on the two command-line interfaces

After installation you actually have two CLIs, and knowing which is which saves confusion later. The console script (pyvorin) is the small licensing tool: it exposes exactly three subcommands — activate, status and check. The full product CLI — bench, run, support, compile, doctor and twenty-odd others — lives behind the module invocation python -m pyvorin. You can confirm both yourself:

pyvorin --help
python -m pyvorin --help

Our advice: activate with the console script, benchmark with the module CLI. That split is deliberate — the licensing surface stays small and auditable — and every command below follows it.

Activate your licence

pyvorin activate PYV-XXXX-XXXX-XXXX

The key can also be passed with the --key flag if your shell makes positional arguments awkward. On success you will see a single line reporting the tier and expiry:

License activated. tier=… expires=…

What just happened, precisely: the client sent one POST request to api.pyvorin.com carrying your licence key and a device fingerprint derived from the hostname, your username and the machine ID. Nothing else — no source code, no environment list, no file names. The server replied with a signed lease, and the client wrote it to ~/.pyvorin/license.json with file mode 0600, meaning only your user account can read it. The licence is bound to this machine; copying the file to another host does not activate it there.

Two commands let you inspect the result:

pyvorin status   # JSON summary: tier, expiry, features
pyvorin check    # runs the hard licence gate

check prints License gate OK and exits 0 when the gate passes; on failure it prints the reason and exits 1, which makes it suitable for CI preflight checks. Activation and entitlement behaviour in depth — offline grace, lease verification, what happens when the network drops — is covered on the activation and entitlement page.

Your first benchmark

Save this as script.py:

def main():
    total = 0
    for i in range(1000000):
        total += i
    return total

if __name__ == "__main__":
    print(main())

A million-iteration integer loop: small enough to read in one glance, slow enough under interpretation to measure. Before benchmarking, ask Pyvorin which functions it can take natively:

python -m pyvorin support script.py

Support report for script.py
Function                       Status               Unsupported
------------------------------------------------------------
main                           COMPILED_FULL        0

COMPILED_FULL means the entire function is a native candidate with zero unsupported constructs. Other statuses exist, and they matter: support is the fastest way to learn whether your real code is worth benchmarking before you spend a single timed run on it. We ran this exact sequence while writing this page.

Now benchmark:

python -m pyvorin bench script.py --function main --runs 5 --warmup 2

Output from our run:

Benchmark: script.py (main)
  warmup: 1
  runs:   3
  correct: True
  status: COMPILED_FULL
  compile_time: 288.455 ms
  min:    0.009 ms
  mean:   0.021 ms
  median: 0.014 ms

Read the fields in this order. correct: True first — the compiled function returned the same answer as the interpreted original, and if that ever reads False the timing below it is worthless. Then status — COMPILED_FULL confirms the native path was taken rather than the fallback. Then the timings, and note that compile_time is reported separately from execution time. Compilation took roughly 300 milliseconds in our run; execution took microseconds. That asymmetry is the whole economics of ahead-of-time compilation: you pay the compile cost once and amortise it across every later call. A one-shot script that runs once is a poor candidate; a function called ten thousand times in a batch job is an excellent one.

Do not quote our timings as expectations. They came from one specific machine and exist here only to show you what the output looks like and how to read it. Your hardware, your Python build and your function will produce different numbers — which is why the benchmarks page publishes a full distribution of 66 workloads, including the 16 that ran slower than CPython, rather than a single marketing figure.

Flags worth knowing on day one

bench has a compact, useful flag set. --runs and --warmup control measurement length; --json emits machine-readable output for CI; --no-vectorize, --no-parallel and --no-pgo isolate each optimisation stage so you can see where a speedup actually comes from. The full list is one command away:

python -m pyvorin bench --help

If you want a same-host comparison against plain CPython in one invocation, python -m pyvorin run script.py --compare runs the same warmup and timed loop on both and reports the speedup directly. For a first taste of the numbers, that single command is the shortest path from install to an honest speedup figure measured on your own hardware.

Choosing a first workload

The example loop above is representative of the code Pyvorin exists for: pure Python, CPU-bound, dominated by an inner loop that CPython would otherwise execute as a long stream of bytecodes. A good second experiment is one of your own functions that you already know is slow — a transformation in an ETL job, a statistical aggregation, a simulation step. A poor second experiment is anything I/O-bound or dominated by library calls into C: JSON parsing, database access, web request handling. Our own 66-workload benchmark suite shows why, with sixteen workloads in exactly those categories running slower than CPython. Measure whatever you like, but set expectations by workload shape, and let the benchmarking correctly page warn you about the measurement mistakes that make slow code look fast.

What happened on your disk

Two caches now exist that did not before. The compiled artefacts from your benchmark are in <site-packages>/.pyvorin_cache/disk_compile, inside the install tree, keyed by a hash of your source, the function name, the compile options and the toolchain's modification times. Re-run the same benchmark and compilation is skipped — the timings you see on the second run are the steady-state ones. Run the benchmark again after editing the script and the entry invalidates automatically. Separately, a ~/.pyvorin_cache directory appeared in your home folder the moment you first imported pyvorin, before any licence activity; that one is created unconditionally and is worth knowing about if you audit file-system writes. Neither cache ever leaves the machine, and the architecture page explains the full compile path, including why the cache lives where it does.

If something goes wrong

Three failure modes cover most first-run problems.

Import or install errors on an unsupported platform. The 1.0.9 wheel is cp312/linux x86_64 only. If you are on another architecture or an older CPython, there is no prebuilt binary for you yet — that is a packaging gap, not a bug in your setup.

The licence gate fails. Run pyvorin status first; it prints the reason in JSON. If the machine is offline, remember that offline validation is checked before the network is consulted, and grace periods apply after lease expiry — the details, including the per-tier grace table, are on the activation page.

Functions fall back instead of compiling. That is normal and safe. Unsupported constructs do not crash your program; the router marks the function and runs honest CPython fallback, and python -m pyvorin support tells you which functions and why. The fallback path is documented in full on the unsupported and fallback page.

Where to go next

Activation and entitlement — what the licence file contains, offline grace periods, and gate semantics.
Benchmarks — the full measured distribution across 66 workloads, wins and losses.
How local compilation works — what happens between import and native execution, and what leaves the machine.
CLI reference — every subcommand of the product CLI.

Last reviewed 14 January 2026 against pyvorin-native 1.0.9 installed at /root/pvfinal. Every command on this page was executed during the review; the support report and benchmark output shown are real captured output, not illustrative fabrications.