PWstudio 安装前必看

本篇是整套安装文档的“总入口”，强烈建议新手从头到尾完整看完本篇，再去看对应系统的安装篇章。文档中已经尽量把常见的坑都提前说明了，遇到问题先回来看看本篇有没有提到。

如果本篇没有能解答你的问题，欢迎使用 AI 工具（比如问 ChatGPT、豆包、DeepSeek 等）搜索报错信息，绝大多数 Linux 报错都能查到解决办法；也可以在 安装问题 Report / 解答 / 查询 / 讨论 里留言。

在动手安装之前，强烈建议先花 5 分钟看完这一节，建立一个整体概念，很多“卡住”都是因为一开始概念没搞清楚。

PWstudio 这个软件包里包含三个部分：

• Qstudio：建模工具，用来搭建/编辑原子结构模型
• Qflow：工作流工具，用来把计算任务可视化地“拖拽”编排起来
• PWmat：真正做第一性原理(DFT)计算的核心计算程序

这是新手最容易搞混的一点，务必先搞清楚：

• 除了 Windows 系统（通过 WSL）之外，PWstudio 这个软件包安装在 Linux 系统上（比如你的 GPU 服务器、工作站）。
• 但是安装好以后，日常使用（建模、拖拽工作流、看计算结果）是通过网页浏览器来完成的，不需要你一直守在服务器跟前敲命令。
• 所以：你的 Linux 服务器需要能联网，并且你用来打开浏览器的这台电脑（可能是另一台 Windows/Mac 电脑），需要能够访问到这台 Linux 服务器（比如同一个局域网，或者服务器有公网/内网可访问的 IP）。
• 如果你是高级用户，也完全可以不用浏览器，直接在 Linux 命令行上用命令提交计算任务，具体见 PWstudio 在命令行提交。
• 推荐浏览器：Google Chrome 或 Microsoft Edge（其它浏览器可能出现兼容性问题，比如密码粘贴不进去等）。
• Qstudio 建模界面需要用鼠标做很多拖拽、旋转、点选操作，建议准备一个鼠标，不要只用触控板。

因为安装过程中的绝大部分操作，都是在 Linux 服务器的命令行上完成的，所以你需要一个能够：

1. 登录到 Linux 服务器（远程连接，类似“远程桌面”，但这里是文字终端）
2. 在你自己的电脑（Windows/Mac）和 Linux 服务器之间互传文件（比如把从网页下载好的驱动、Docker 安装包，传到服务器上）

这样的工具很多，比较常见、新手友好的是 MobaXterm（Windows 上免费好用，同时支持登录终端和图形化拖拽传文件），也可以用 PuTTY + WinSCP 组合，或者 Xshell 等，效果都类似，选一个顺手的就行。

如果你还不会用这类工具登录服务器、上传下载文件，我们专门写了一篇保姆级教程，请先看这里：新手教程：如何用 MobaXterm 登录服务器并上传下载文件

在安装过程的命令行部分，绝大多数情况下你只需要“复制 + 粘贴”命令，而不需要自己一个字一个字去敲。原因很简单：手动敲命令非常容易打错字符，尤其是一些长得很像的字符（比如字母 l（小写 L）和数字 1（数字 1）很容易看混），打错一个字符命令就会报错甚至造成意料之外的后果。所以本教程强烈建议：

1. 先在网页文档上，把要执行的命令整行选中并复制（Windows/Linux 上是 Ctrl+C，Mac 上是 Cmd+C）
2. 切换到你的终端窗口（比如 MobaXterm 的终端），对于一些终端软件，只需要在终端里点击鼠标右键，就会自动把刚才复制的内容粘贴进去（这是很多终端工具，包括 MobaXterm、xshell 等的默认行为）。如果右键不能粘贴，可以尝试 Shift + Insert 组合键，或者看终端软件菜单里的“粘贴”选项。
3. 粘贴之后，按回车执行

极其重要的提醒：命令行前面那一段形如 [lxkt@localhost ~]$ 或者只有一个 $ / # 的部分，叫做“命令提示符”，它不是命令本身，只是终端用来提示“当前在等你输入”的符号。复制命令的时候，千万不要把提示符也一起复制进去，只需要复制提示符后面真正的命令内容。如果你把提示符也当成命令的一部分粘贴执行，终端会报类似 “command not found” 的错误，这是新手很常遇到的问题，一定要注意。

安装文档里，你会看到一些命令中包含形如 $(uname -r) 、 $USER 这样的写法，例如：

sudo yum install -y gcc kernel-devel-$(uname -r) kernel-headers-$(uname -r)

这里的 $(uname -r) 是命令的一部分，你不需要，也不应该把它替换成别的内容（比如替换成你自己的用户名）。uname -r 是一个 Linux 系统命令，作用是“查询当前系统内核的版本号”，$(…) 表示“先执行括号里的命令，再把结果代入到外面这条命令里”。所以整条命令的意思是“自动查出我当前系统的内核版本号，然后安装与这个版本号匹配的开发包”。你只需要原样整行复制粘贴即可，不需要做任何修改。

同样地，命令里出现的 $USER 也是系统自动变量，会自动被替换成你当前登录的用户名，同样不需要你手动修改。

• nvidia-smi 这个命令，nvidia 和 smi 中间是一个短横线 -，没有空格。有些人会不小心敲成 “nvidia - smi” 或 “nvidia smi”，这样会报错说命令找不到。
• 注意区分小写字母 l（L）和数字 1，很多命令和路径里两者都出现，看起来非常像。
• 同理还是建议：能复制粘贴，就不要手动敲。

显卡(GPU)驱动的安装、Docker 的安装、nvidia-container-toolkit 的安装，都需要服务器的 root 权限（或者 sudo 权限）。如果你自己没有这个权限，请联系服务器管理员，为你开通 sudo 权限，或者请管理员按照本教程帮你安装。

1. CPU 必须是 x86_64 架构
2. 如果要用 GPU 版本，显卡必须是 NVIDIA 显卡。支持市面上绝大多数计算显卡如 1080ti、3080ti、3090、4090、5090 等等 (或同等架构的显卡). 可以在此链接gpu 卡性能对比查询显卡型号和对应架构。
3. 内存建议 128G 以上；128G 以下只能安装体验测试，不适合真正拿来跑 qflow 计算作业
4. 宿主机显卡驱动版本要能支持 CUDA 12.1 及以上（1080ti 显卡的驱动版本不要超过 CUDA 12.8，否则可能不兼容）
5. 假设你的 Linux 工作站已经装好了操作系统（CentOS 7.9 / Rocky 8.10 / Ubuntu 24.04，更高版本一般也可以），但还没装任何 PWstudio 相关的软件
6. 如果是 Windows 系统，需要先安装 WSL（Windows 上的一个 Linux 子系统），具体见 windows11_wsl2 安装 或 windows11_wsl2 cpu 安装。Windows WSL 目前只提供 CPU 版本。

安装过程中要用到的几个安装包（NVIDIA 显卡驱动、Docker 离线包、nvidia-container-toolkit 离线包等），下载链接都是普通的网页链接， 也就是说你需要用浏览器去下载它们，而不是在 Linux 服务器的命令行里直接下载（当然如果你的服务器能直接访问外网，也可以在命令行用 wget 直接下载，文档里也给出了对应的命令）。

如果你是在自己的电脑上用浏览器下载好安装包，那么接下来还需要把这些下载好的文件，上传到 Linux 服务器上，才能继续安装。 这一步就要用到前面 0.3 节提到的 MobaXterm（或 WinSCP 等）这样的工具了——它既能让你登录服务器命令行，也能让你把本地文件拖拽上传到服务器。 如果还不熟悉，请先看 MobaXterm 新手教程。

1. 显卡(GPU卡)驱动的安装, docker 的安装, nvidia-container-toolkit 的安装需要服务器的root权限,
2. 建议使用安装了 linux 系统的 gpu 服务器来安装, 个人 windows 系统 pc的算力可能不够

1. cpu 必须是 x86_64
2. 显卡(GPU卡)必须是 nvidia, 目前支持 1080ti, 3080ti, 3090, 4090 d, 4090 等
3. 内存建议是 128 G 以上, 128 G 以下只能安装测试, 不适合跑 qflow 作业

1. 宿主机显卡驱动的版本要能支持 cuda 12.1 及以上
2. 1080ti 显卡的显卡驱动不要超过 cuda 12.8

查看服务器是否有显卡：如果命令有输出（能看到一行包含显卡型号的信息），说明识别到了显卡；如果什么都没输出，说明没有识别到显卡，或者服务器本身没插显卡。

lspci | grep -i nvidia

查看显卡驱动是否安装及显卡驱动对应的版本，如果能看到显卡型号、驱动版本、CUDA 版本等信息，说明驱动已安装，可以跳过对应安装步骤；如果提示 “nvidia-smi: command not found” 或者 “-bash: nvidia-smi: 未找到命令”，说明驱动还没装，需要按照后面篇章安装。

nvidia-smi

注意：nvidia-smi 中间是短横线连接，没有空格，输错很容易导致命令找不到，建议直接复制粘贴。

• centos/rocky 系列 linux 查看系统版本

cat /etc/redhat-release

• ubuntu/debain 系列 linux 查看系统版本

cat /etc/os-release

1. 通过本篇获得系统版本
2. 自己判断是要安装 cpu 版本，还是 gpu 版本
3. 根据系统版本和对应 cpu/gpu 版本，进入对应篇章进行安装
4. 安装中遇到问题可以查看 常见问题篇章 或 通过 AI 工具查询
5. 通过 PWstudio 工作流功能验证 篇章验证
6. 遇到问题或有什么安装心得可以在 问题 Report留言和评论

总结（安装大致要经过哪些步骤，心里先有个数）：

• cpu 版本：安装 Docker → 安装 license 许可服务 → 启动容器
• gpu 版本：安装显卡驱动 → 安装 Docker → 安装 nvidia-container-toolkit → 安装 license 许可服务 → 启动容器

以上四五个步骤中，如果你的机器已经装过驱动/Docker 了，对应的步骤可以跳过。 整个流程如果是第一次装，全部步骤走下来（包含几次系统重启、以及大约 12G 大小的 qflow 镜像包下载，下载可能需要 15 分钟左右）， 预计总共需要 30 分钟到 1 小时，具体取决于你的网络速度和机器性能，请耐心一点，不用担心是不是卡住了。