Mahdi
All posts
vwindowstoolchain

Installing V on Windows, and the failure that looks like a compiler bug

Getting V working on Windows in under five minutes, plus the version mismatch between v.exe and vlib that produces errors that read like a broken compiler.

Why this is worth the trouble. The install is five minutes of work, and the language it installs is compiling a production-grade toolchain, shipping an MCP server to coding agents, and growing its standard library steadily. The failure below is worth writing down because nothing tells you it happened — not because V is fragile.V is unusually easy to install. One zip, one directory, no installer, no registry, no runtime to install separately.That is also the problem. Nothing checks that what you downloaded is internally consistent, so a stale checkout gives you error messages that blame the compiler.The installGrab a release zip, not the source repository:
$ProgressPreference = "SilentlyContinue"
Invoke-WebRequest `
  -Uri "https://github.com/vlang/v/releases/download/0.5.2/v_windows.zip" `
  -OutFile "$env:TEMP\v.zip"
Expand-Archive "$env:TEMP\v.zip" -DestinationPath "$env:LOCALAPPDATA\Programs\v" -Force
Unzipping gives you v.exe and a vlib directory, and those two have to come from the same release:
%LOCALAPPDATA%\Programs\v\
  v.exe
  vlib\
    os.v ... (10,690 files)
Put that directory on PATH. No VROOT is needed for the release build — it knows where it lives.Confirming it worksv version is not a sufficient check. A mismatched installation reports a perfectly plausible version and still is broken. This is the check that matters:
@'
module main
import "time"

fn main() {
    println("now -> " + time.now().format_ss_micro())
}
'@ | Set-Content t.v
v run t.v
now -> 2026-09-30 17:10:17.925000
The stdlib import is the part that has to work. A v hello.v with no imports compiles fine on a broken install, which is exactly why v version is not enough.Two API details that cost me a few minutesBoth are my own mistakes, and both are the kind of thing you hit in the first ten minutes.exit is a builtin, not a member of os:
fn main() {
    exit(0)         // correct
    os.exit(0)      // error: unknown function: os.exit
}
String helpers are methods on the type, not functions in a module:
parts := "a,b,c".split(",")   // correct
parts := strings.split(s, ",")  // there is no strings.split
println(parts.join(","))
println("mahdi".to_upper())
println("  x  ".trim_space())
The second one surprised me because Go trains you to look in strings. V's strings module has seven free functions, plus a Builder and a set of string-distance helpers; the manipulation you reach for daily lives on the type.
println("a-b-c".replace("-", "/"))
println("x".repeat(3))
v fmt rewrites aggressively — and converges nowv fmt reformats hard, which is the point: it removes formatting as something to argue about. A deliberately mangled file — single-line struct, no spaces, single-quoted strings — comes back multi-line and properly spaced.The thing I would flag is different from what I expected. I assumed the formatter would not settle in one pass, and wrote that down here as a limitation. Checked on 0.5.2, it does: a second v fmt -w produces no change, and v fmt -verify exits clean on the file the first pass just wrote.
v fmt -w messy.v      # rewrites it
v fmt -w messy.v      # no further change
v fmt -verify messy.v # exit 0
So v fmt -verify works as a CI gate the way gofmt -l does. I have left the claim out rather than repeat it, because a limitation I could not reproduce is worse than no limitation at all.The failure: v.exe newer than vlibThis is the installation that broke, and the errors it produced.The checkout had been on master and someone had run v self, which rebuilt v.exe from a much newer commit than the vlib it was left next to. It had even left a backup behind, named for the version that used to work:
v.exe.bak-0.5.2-c9b806b
Two different errors came out of that state, and neither mentions a version.Programs without imports compiled. Anything importing the standard library failed to build:
main.v:2:1: builder error: cannot import module ""time"" (not found)
That reads like a missing file, and the file was not missing — vlib/time/chrono.v was right there with module time on line 5. Setting VROOT did not help.Swapping in a different build made it worse, in the opposite direction:
C:/Users/xman/v/vlib/builtin/int.v:202:12: error: unknown type `u128`
Now vlib was too new. The compiler does not know about a 128-bit integer the standard library uses.The actual rule, which I had to work out from two broken states:v.exe agevlib ageResultsamesameworksneweroldercannot import module "os" (not found)oldernewerunknown type 'u128'The error names a module or a type, never a version. Nothing in the output says these two files are from different days.What to do about itUnzip the release again, over the top. Do not try to fix a git checkout with v self — that is what produced the broken state, because the checkout's vlib and its compiler come from master at whatever moment each was last touched.If you want to work on V itself rather than use it, treat the checkout as a build environment rather than an installation:
git clone https://github.com/vlang/v
cd v
v self        # rebuild the compiler from the current source
v version     # then verify with an actual stdlib import, not this
When something impossible happens, compare the dates:
Get-Item v.exe, vlib\builtin\int.v | Select-Object Name, LastWriteTime
VerdictFor a language you are evaluating, the release zip is the right way in. Five minutes to get it working, and the failure mode cost twenty — because the error messages point at the standard library instead of at the installation.That is the main thing I would want changed: a version check between v.exe and vlib at startup would have turned a confusing half hour into one sentence.One more thing, now that I have the code for these posts checked by a script rather than by reading: I had two claims in here that a single run disproved. One said v fmt does not converge, and it does. The other was about quoted imports in the probes, which failed to compile for a reason that had nothing to do with the claim they were testing.Both errors were invisible while writing and obvious once executed. That is the argument for checking: not that the claims were probably right, but that "probably right" is not a standard worth publishing.

Related