Docs / Troubleshooting
文档 / 故障排查
Troubleshooting
故障排查
The failures people actually hit, what causes them, and what to do. When
in doubt, re-run with --debug first -- it usually names the
problem outright.
pip refuses to install: externally-managed-environment
pip 拒绝安装:externally-managed-environment
Debian and Ubuntu mark the system Python as managed by the distribution
(PEP 668), so pip install into it is blocked. This is the
distribution's rule, not AnyVM's. Use pipx:
Debian 和 Ubuntu 把系统 Python 标记为由发行版管理(PEP 668),
所以往里面 pip install 会被拦住。这是发行版的规矩,不是 AnyVM 的。
改用 pipx:
$ sudo apt-get install -y pipx $ pipx install anyvm.py $ pipx ensurepath # first time only, then reopen the shell
Or a virtualenv, or just run the single file directly:
或者用虚拟环境,再或者直接跑那个单文件:
$ curl -O https://raw.githubusercontent.com/anyvm-org/anyvm/main/anyvm.py $ python3 anyvm.py --os freebsd
The guest needs a newer QEMU than my distro ships
这个系统需要比发行版更新的 QEMU
Several guest and architecture combinations do not run on QEMU 8.2, which is what current LTS distributions ship. On a Linux x86_64 host AnyVM handles this itself: it detects the too-old system QEMU and downloads a pinned QEMU 10.2.3 for exactly those cases -- Ubuntu on riscv64 26.04, s390x and ppc64le 22.04, and OpenEuler on loongarch64. Nothing to configure. 有几个系统和架构的组合在 QEMU 8.2 上跑不起来,而目前各家 LTS 发行版 自带的正是这个版本。在 Linux x86_64 宿主上 AnyVM 自己会处理:检测到系统 QEMU 太旧,就为这些特定组合下载固定版本的 QEMU 10.2.3 —— 具体是 Ubuntu 的 riscv64 26.04、s390x 和 ppc64le 22.04,以及 OpenEuler 的 loongarch64。你不用配置什么。
On other hosts you need a newer QEMU yourself. The full list of which combination needs what is in guest notes. 其他宿主上就得你自己装新版 QEMU。哪个组合需要什么,完整清单在 系统说明里。
An aarch64 guest hangs right after "UEFI firmware (version 2025.11-...)"
aarch64 客户机在 "UEFI firmware (version 2025.11-...)" 之后就卡住
That line is the last thing edk2 prints before it sets up the MMU.
Builds from edk2-stable202508 through edk2-stable202602 -- Ubuntu 26.04's
qemu-efi-aarch64 2025.11 among them -- switch the CPU to
LPA2 (52-bit) mode while the early page tables in flash are still in the
old format, so under -cpu max, QEMU's TCG default for most
aarch64 guests, the firmware faults on its very next instruction and spins
forever; the guest never reaches its bootloader
(tianocore/edk2#11962,
fixed in edk2-stable202605). The fixed 2026.05 build is no way out either:
on QEMU 10.2.1 it raises a Synchronous Exception when the
loaders of FreeBSD 12.4 and openEuler 22.03 (GRUB 2.06) hand over to the
kernel. Nothing to configure: AnyVM reads the build stamp out of the host
firmware and, when it is a 2025.08 or later build, boots with Ubuntu
24.04's edk2 2024.02 firmware instead: the unmodified
QEMU_EFI.fd from Ubuntu's qemu-efi-aarch64
2024.02-2ubuntu0.9 package, published by
anyvm-org/firmware
and downloaded once (2 MB, sha256-checked).
--firmware <path|URL> overrides everything; passing that
firmware's release URL uses it on any host.
这一行是 edk2 设置 MMU 之前打印的最后一句。edk2-stable202508 到
edk2-stable202602 之间的版本 —— Ubuntu 26.04 的 qemu-efi-aarch64
2025.11 就是其中之一 —— 会在 flash 里的早期页表还是旧格式的时候就把 CPU 切到
LPA2(52 位)模式,于是在 -cpu max(QEMU TCG 下大多数 aarch64
客户机的默认 CPU)下,固件紧接着的一条指令就出错,然后永远转圈;客户机根本
到不了引导程序(tianocore/edk2#11962,
edk2-stable202605 已修复)。修好的 2026.05 版也不能用:在 QEMU 10.2.1 上,
FreeBSD 12.4 和 openEuler 22.03(GRUB 2.06)的引导程序把控制权交给内核时,
它会报 Synchronous Exception。不用配置什么:AnyVM 会从宿主机固件里读出版本戳,
发现是 2025.08 及以后的版本,就改用 Ubuntu 24.04 的 edk2 2024.02 固件启动:Ubuntu
qemu-efi-aarch64 2024.02-2ubuntu0.9 软件包里原封不动的 QEMU_EFI.fd,由
anyvm-org/firmware
发布,只下载一次(2 MB,校验 sha256)。--firmware <路径|链接>
覆盖一切;传那份固件的 release 链接,就能在任何宿主机上用它。
-cpu max,lpa2=off is not a workaround: it trips a second bug in
the same firmware, which then faults while loading its own DXE core.
-cpu max,lpa2=off 不是办法:它会撞上同一份固件里的另一个 bug,
加载自己的 DXE core 时照样出错。
The boot times out and gets killed
启动超时被杀掉了
AnyVM kills QEMU and retries once when a guest does not come up in time. The default window is 600 seconds, already raised to 1200 for OpenBSD on aarch64 and to 1800 whenever no hardware acceleration is available. If you are on a slow host or an emulated architecture, give it more: 虚拟机没能按时起来时,AnyVM 会杀掉 QEMU 并重试一次。默认窗口是 600 秒,OpenBSD aarch64 已经提到 1200 秒,没有硬件加速时提到 1800 秒。如果你的 机器慢,或者跑的是模拟架构,就再给它多一点:
$ anyvm --os solaris --boot-timeout-sec 2400 --debug
An explicit value always overrides the automatic ones. If the guest is
genuinely stuck rather than slow, --debug plus
--serial will show you where it stopped.
你写死的值永远盖过自动值。如果虚拟机不是慢,而是真的卡住了,
--debug 配上 --serial 能让你看到它停在哪。
Everything is slow
整体都很慢
Check whether you are on TCG. Any architecture that is not your host's runs under software emulation, which is roughly 10-50x slower than hardware acceleration -- that is inherent to emulating a foreign CPU, not something to tune away. 先看是不是在跑 TCG。只要不是宿主自己的架构,都得靠软件模拟,比 硬件加速慢 10 到 50 倍 —— 这是模拟异构 CPU 的固有代价,不是调参能解决的。
For a same-architecture guest that is still slow, acceleration is probably
not being used. On Linux confirm /dev/kvm exists and is
readable, on macOS that HVF is available, on Windows that the Windows
Hypervisor Platform is on. --debug reports which accelerator
was selected.
如果是同架构的虚拟机还这么慢,多半是加速没用上。Linux 上确认
/dev/kvm 存在且可读,macOS 上确认 HVF 可用,Windows 上确认
Windows Hypervisor Platform 已开启。--debug 会告诉你最后选中的是
哪个加速器。
Windows: QEMU aborts partway through boot
Windows:QEMU 启动到一半中止
Some guests hit instructions the WHPX emulator cannot decode. AnyVM already
handles this in two ways: it relaunches the VM under TCG when QEMU aborts
mid-boot under auto-enabled WHPX, and it skips WHPX entirely for GhostBSD,
which reliably fails with failed to decode instruction f 10.
有些系统会碰到 WHPX 模拟器解不了的指令。AnyVM 已经从两方面处理:
自动启用 WHPX 后 QEMU 若在启动中途中止,就改用 TCG 重开一次;而 GhostBSD 一定会
以 failed to decode instruction f 10 失败,所以直接跳过 WHPX。
Passing --whpx explicitly disables both safety nets. To rule
out the accelerator by hand, use --tcg.
显式写 --whpx 会把这两道保险都关掉。想手动排除加速器
的嫌疑,用 --tcg。
Guests segfault randomly on a nested AMD host
嵌套 AMD 宿主上虚拟机随机段错误
On a nested AMD KVM host -- KVM running inside WSL2 or Hyper-V -- nested
AMD-V corrupts the guest's AVX512 state, which makes modern guests such as
Ubuntu 26.04 segfault at random. AnyVM detects this and drops AVX512 from
-cpu host automatically. Bare-metal hosts keep the full
feature set. Override with --cpu-type if you need to.
在嵌套的 AMD KVM 宿主上 —— 也就是 KVM 跑在 WSL2 或 Hyper-V 里面
—— 嵌套的 AMD-V 会破坏虚拟机的 AVX512 状态,导致 Ubuntu 26.04 这类较新的系统随机
段错误。AnyVM 检测到这种情况会自动从 -cpu host 里去掉 AVX512。裸机
宿主保留完整特性。需要的话用 --cpu-type 覆盖。
NFS fails on a Linux host: port 111 is already in use
Linux 宿主上 NFS 失败:111 端口已被占用
OpenBSD, NetBSD and DragonFly BSD guests are NFSv3-only, so they reach the
bundled server through its portmapper on port 111. On Windows and macOS
hosts that port is free and unprivileged. On Linux it is usually owned by
the system rpcbind, or restricted to root.
OpenBSD、NetBSD、DragonFlyBSD 只支持 NFSv3,所以要通过 111 端口上的
portmapper 才能连到自带的服务器。在 Windows 和 macOS 上这个端口是空的,也不需要
特权。在 Linux 上它通常被系统的 rpcbind 占着,或者只有 root 能用。
Use the host's kernel NFS server for those three guests on Linux:
在 Linux 上,这三个系统改用宿主的内核 NFS 服务器:
$ anyvm --os openbsd --sync sys-nfs -v "$PWD:/data"
There is deliberately no automatic fallback between nfs and
sys-nfs -- silently switching backends would hide which one
you are actually running.
nfs 和 sys-nfs 之间故意不做自动切换 ——
悄悄换后端会让你搞不清自己实际在用哪个。
The guest wedges when I share a directory
一共享目录,虚拟机就卡死
Most likely NetBSD on sparc64. The QEMU sun4u machine boots only off the
CMD646 PCI IDE controller, whose TCG emulation loses interrupts under
sustained concurrent network and disk DMA -- which is exactly what a live
sshfs or nfs mount produces. That is why
-v defaults to scp there. If you overrode
--sync, put it back.
多半是 sparc64 上的 NetBSD。QEMU 的 sun4u 机器只能从 CMD646 这块
PCI IDE 控制器启动,而它的 TCG 模拟在网络和磁盘 DMA 持续并发时会丢中断 —— 实时的
sshfs 或 nfs 挂载制造的正是这种压力。所以那里的
-v 默认走 scp。你要是改过 --sync,改回去。
More generally: if a live mount destabilises a guest, a one-shot
rsync or scp copies the data in without holding
a connection open for the whole session.
更一般地说:只要实时挂载会让某个虚拟机不稳定,就改用一次性的
rsync 或 scp 把数据拷进去 —— 不用整个会话都挂着连接。
The VNC web UI is not on port 6080
VNC 网页控制台不在 6080 端口
It auto-increments when the port is taken -- 6081, 6082 and so on. The
actual URL is printed at startup. --vnc off disables the web
UI entirely if you do not want it.
端口被占就自动往后顺延 —— 6081、6082 这样。实际地址在启动时会打印
出来。不想要的话,--vnc off 可以把网页控制台整个关掉。
Downloads fail behind a corporate proxy
在公司代理后面下载失败
AnyVM reads http_proxy, https_proxy and
all_proxy from the environment (upper case too) and downloads
images and tools through them. Both HTTP proxies and SOCKS5 are supported
natively:
AnyVM 会从环境变量里读 http_proxy、
https_proxy 和 all_proxy(大写形式也认),并通过它们
下载镜像和工具。HTTP 代理和 SOCKS5 都原生支持:
http://host:portsocks5://host:port-- DNS resolved locally —— DNS 在本地解析socks5h://host:port-- DNS resolved by the proxy —— DNS 交给代理解析- credentials as带认证信息写作
user:pass@host:port
no_proxy is honoured. SOCKS4 is not supported.
no_proxy 会被遵守。SOCKS4 不支持。
Plan 9 boots but ignores -v
Plan 9 能启动,但 -v 没反应
Expected on a Windows or macOS host. Plan 9's sync backend is 9P: the host
mounts the guest's exportfs share through the Linux kernel
v9fs client (mount -t 9p, needs root or sudo), so it only
works from a Linux host. Everything else about the guest -- booting,
running commands -- works everywhere; only directory sync is skipped.
在 Windows 或 macOS 宿主上这是预期行为。Plan 9 的同步后端是 9P:
由宿主通过 Linux 内核的 v9fs 客户端去挂载虚拟机的 exportfs 共享
(mount -t 9p,需要 root 或 sudo),所以只有 Linux 宿主能用。这个
系统的其他部分 —— 启动、跑命令 —— 在哪都正常,只是跳过了目录共享。
ReactOS says "Cannot find the image link"
ReactOS 报 "Cannot find the image link"
Update AnyVM, or add --arch i386. ReactOS is published for
32-bit x86 only. Current AnyVM resolves --os reactos to
i386 by itself; older versions defaulted to the host
architecture and went looking for an x86_64 image that does not
exist:
升级 AnyVM,或者加上 --arch i386。ReactOS 只发布 32 位 x86
版本。现在的 AnyVM 会自己把 --os reactos 解析成 i386;
旧版本按宿主架构去找,于是找一个并不存在的 x86_64 镜像:
$ anyvm --os reactos --arch i386The RISC OS console ignores the keyboard and the mouse
RISC OS 控制台不响应键盘和鼠标
Update your pins. Keyboard and mouse work with the current
riscos-builder and anyvm releases: anyvm attaches usb-kbd and
usb-mouse, and RISC OS's own USBDriver (its HID
class drivers are compiled into that module, which is why
*Modules shows no separate one) drives both. Older releases
were view-only because of a bug in the patched QEMU, not RISC OS: the
second port reset RISC OS issues when the Wimp starts stopped the USB
bus's frame counter, so the keyboard driver attached and then never
received a single interrupt transfer. This page used to say the ROM had no
keyboard driver; that was wrong. Two things remain true: the boot still
prints No keyboard present - autobooting, which only means
the kernel's 5-second boot-time USB discovery found nothing that early
(the desktop rescans), and a QEMU usb-tablet never moves the
pointer, because it rejects the SET_PROTOCOL request RISC
OS's mouse driver requires -- use usb-mouse. The guest can
of course still be driven without a console:
请更新版本号。当前的 riscos-builder 和 anyvm 发布版里键盘和鼠标
都能用:anyvm 会挂上 usb-kbd 和 usb-mouse,RISC OS 自带的
USBDriver(HID 类驱动编在这个模块里,所以 *Modules 看不到
单独的驱动)负责驱动它们。旧版本只能看不能操作,原因在打过补丁的 QEMU 而不是
RISC OS:Wimp 启动时 RISC OS 会对端口做第二次 reset,之后 USB 总线的帧计数停了,
键盘驱动虽然挂上了,却再也收不到任何中断传输。本页以前说 ROM 里没有键盘驱动,
那是错的。有两点仍然成立:开机仍会打印 No keyboard present -
autobooting,这只说明内核开机 5 秒的 USB 发现窗口里没枚举到东西(桌面会
重新扫描);QEMU 的 usb-tablet 永远动不了指针,因为它拒绝 RISC OS
鼠标驱动必需的 SET_PROTOCOL 请求 —— 请用 usb-mouse。
当然,不用控制台也照样可以驱动客机:
$ anyvm --os riscos -- Cat $Filing a bug
提交问题
Issues go to
anyvm-org/anyvm.
Include the full command, the host OS and architecture, your QEMU version,
and the output with --debug. If the guest boots but
misbehaves afterwards, the serial log is the useful part:
issue 提到
anyvm-org/anyvm。
请附上完整命令、宿主系统和架构、QEMU 版本,以及加了 --debug 的输出。
如果虚拟机能起来但之后行为异常,串口日志才是有用的那部分:
$ anyvm --os netbsd --arch sparc64 --debug --serial 7000
If the problem is in the image rather than the launcher -- a package missing, a service not starting -- the builder repository for that guest is the better place. Guest notes links each one. 如果问题出在镜像而不是启动器 —— 比如少了某个包、某个服务没起来 —— 那更适合去对应系统的 builder 仓库提。系统说明 里有每一个的链接。