virtinst 不是一个可以通过 pip 下载的普通 Python 包。

virtinst 是一个命令行工具和 Python 库，它是 libvirt 虚拟化工具集的一部分，它通常作为操作系统的一个软件包来安装，而不是通过 Python 的包管理器。

"下载" virtinst 的正确方式是 安装你所用操作系统对应的软件包。

核心概念：virtinst, libvirt, 和 python3-libvirt

你需要理解这三个角色的关系：

1. libvirt: 这是核心的虚拟化 API 和后台守护进程（libvirtd），它提供了一个统一的接口来管理各种虚拟化平台（如 KVM, Xen, VMware, VirtualBox 等）。没有 libvirt，virtinst 无法工作。
2. python3-libvirt: 这是 libvirt 的 Python 绑定，它让你可以在 Python 脚本中调用 libvirt 的功能，这是 virtinst 这个 Python 库所依赖的底层库。
3. virtinst: 这是一个建立在 libvirt 和 python3-libvirt 之上的高级工具集，它提供了 virt-install, virt-clone, virt-xml 等非常方便的命令行工具，同时也包含了一个 Python 模块,用于在脚本中创建虚拟机。

安装 virtinst 的过程，实际上是安装一个包含了 virtinst 命令行工具及其 Python 模块的操作系统软件包，这个包会自动处理 libvirt 和 python3-libvirt 的依赖关系。

如何在不同操作系统上安装 virtinst

以下是在主流 Linux 发行版上的安装方法。

基于 Debian / Ubuntu 的系统 (如 Ubuntu, Mint)

这是最常见的情况，通常使用 apt 包管理器。

# 更新软件包列表
sudo apt update
# 安装 virtinst 及其核心依赖
# 这个包会自动安装 libvirt, qemu, python3-libvirt 等必需组件
sudo apt install -y virtinst libvirt-daemon-system libvirt-clients bridge-utils

验证安装：

安装完成后，你可以直接使用 virt-install 命令，并检查 Python 模块是否可用。

# 检查命令是否安装成功
virt-install --version
# 检查 Python 模块是否可以导入
python3 -c "import virtinst; print(virtinst.__file__)"
# 如果成功，它会输出 virtinst 模块的安装路径，
# /usr/lib/python3/dist-packages/virtinst/__init__.py

基于 RHEL / CentOS / Rocky / AlmaLinux 的系统

这些系统使用 yum 或 dnf 包管理器。

# 对于使用 dnf 的新系统 (CentOS 8+, RHEL 8+, Fedora)
sudo dnf install -y virt-install libvirt qemu-kvm
# 对于使用 yum 的旧系统 (CentOS 7, RHEL 7)
sudo yum install -y virt-install libvirt qemu-kvm

重要提示 (RHEL/CentOS): 你可能需要启用 EPEL (Extra Packages for Enterprise Linux) 仓库，因为 virtinst 可能不在默认仓库中。

# 对于 RHEL/CentOS 7
sudo yum install -y epel-release
# 对于 RHEL/CentOS 8+
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

验证安装： 与 Ubuntu 系统相同。

virt-install --version
python3 -c "import virtinst; print(virtinst.__file__)"

基于 Arch Linux 的系统

Arch 使用 pacman 包管理器。

sudo pacman -S --noconfirm virt-install qemu libvirt

安装后，你需要启动并启用 libvirtd 服务。

sudo systemctl enable --now libvirtd

验证安装： 同样使用上述命令进行验证。

安装后如何使用 virtinst 的 Python 模块

一旦通过系统包管理器成功安装，你就可以在 Python 脚本中导入并使用 virtinst 了。

一个简单的 Python 脚本示例：

这个脚本会连接到本地的 libvirt 守护进程,并列出所有正在运行的虚拟机。

#!/usr/bin/env python3
import sys
import virtinst
def list_vms():
    """
    连接到本地 libvirt 并列出所有域（虚拟机）
    """
    try:
        # 1. 连接到本地 libvirt 守护进程 (默认是 qemu:///session)
        #    如果要管理系统级虚拟机，使用 qemu:///system
        conn = virtinst.connect.get_uri("qemu:///system")
        # 或者直接使用 conn = virtinst.connect.get_uri()，它会尝试默认连接
        # 2. 获取所有域的列表
        domains = conn.list_all_domains()
        if not domains:
            print("当前没有找到任何虚拟机。")
            return
        print("找到以下虚拟机:")
        print("-" * 30)
        for domain in domains:
            # domain 是一个 Domain 对象
            name = domain.name()
            state = domain.state()[0]  # 状态是一个元组，取第一个元素
            state_str = "运行中" if state == 1 else "已关闭"
            print(f"- 名称: {name:<15} | ID: {domain.ID():<5} | 状态: {state_str}")
    except Exception as e:
        print(f"发生错误: {e}", file=sys.stderr)
        print("请确保 libvirtd 服务正在运行，并且你有权限访问。")
        sys.exit(1)
if __name__ == "__main__":
    list_vms()

如何运行脚本：

1. 确保你已经按照上面的步骤安装了 virtinst。
2. 将上面的代码保存为文件，list_vms.py。
3. 给脚本执行权限：chmod +x list_vms.py
4. 运行脚本：python3 list_vms.py

如果一切正常，它会列出你的系统上通过 libvirt 管理的所有虚拟机。

故障排除

• ModuleNotFoundError: No module named 'virtinst'

  • 原因：virtinst 没有正确安装，或者你安装的 Python 环境与安装软件包的环境不一致（你在虚拟环境中，而软件包安装在了主系统中）。
  • 解决：重新检查你的操作系统包管理器安装步骤，确保 virtinst 软件包已安装。

• libvirt.libvirtError: Cannot open socket '/var/run/libvirt/libvirt-sock': Permission denied

  • 原因：你尝试连接 qemu:///system，但你的用户没有权限访问 libvirt 的系统级套接字，通常只有 root 用户或 libvirt 组的用户才有此权限。
  • 解决：
    1. 将你的用户添加到 libvirt 组：sudo usermod -aG libvirt $USER
    2. 注销并重新登录，让组 membership 生效。
    3. 或者，在脚本中连接 qemu:///session，这是用户级的连接，权限要求较低,但通常只能管理用户自己创建的虚拟机。

• libvirt.libvirtError: Failed to connect socket to '/var/run/libvirt/libvirt-sock': No such file or directory

  • 原因：libvirtd 守护进程没有运行。
  • 解决：启动并启用服务。

    # 对于 systemd 系统 (Ubuntu, CentOS 7+, etc.)
    sudo systemctl start libvirtd
    sudo systemctl enable libvirtd