Read This Before Installing PWstudio

This page is the “main entry point” for the whole installation guide. If you're new to this, we strongly recommend reading it from start to finish before moving on to the installation chapter for your specific system. Most of the common pitfalls are already covered here — if you run into trouble later, come back and check whether it's already answered on this page.

If this page doesn't answer your question, feel free to search the error message with an AI tool (ChatGPT, DeepSeek, etc.) — most Linux errors already have a documented fix out there. You're also welcome to leave a comment on Installation Q&A / Answers / Search / Discussion.

Before you start installing anything, spend 5 minutes reading this section to get the big picture. Most people get “stuck” simply because they didn't have these basic concepts clear from the start.

The PWstudio package contains three parts:

• Qstudio: a modeling tool used to build/edit atomic structure models
• Qflow: a workflow tool used to visually “drag and drop” your calculation tasks together
• PWmat: the core computation engine that actually performs first-principles (DFT) calculations

This is the point beginners mix up most often, so make sure it's clear from the start:

• Except for Windows (via WSL), the PWstudio package is installed on a Linux system (e.g. your GPU server or workstation).
• However, once it's installed, day-to-day use (modeling, dragging workflows together, viewing results) happens through a web browser — you don't need to sit at the server typing commands all the time.
• So: your Linux server needs network access, and the computer you use to open the browser (which may be a completely different Windows/Mac machine) needs to be able to reach that Linux server (e.g. on the same LAN, or the server has a public/internal IP that's reachable).
• If you're an advanced user, you can skip the browser entirely and submit calculation jobs directly from the Linux command line — see Submitting PWstudio jobs from the command line.
• Recommended browsers: Google Chrome or Microsoft Edge (other browsers may have compatibility issues, e.g. pasting a password may not work).
• The Qstudio modeling interface relies heavily on mouse operations (drag, rotate, click-select), so we recommend using an actual mouse rather than just a trackpad.

Since almost all of the installation steps happen on the Linux server's command line, you'll need a tool that can:

1. Log in to the Linux server (a remote connection, similar to “remote desktop” but as a text terminal)
2. Transfer files between your own computer (Windows/Mac) and the Linux server (e.g. uploading a driver or Docker installer you downloaded from a webpage)

There are many such tools; a common, beginner-friendly one is MobaXterm (free and easy to use on Windows, supports both terminal login and drag-and-drop file transfer). You can also use a PuTTY + WinSCP combo, Xshell, or similar — the effect is similar, just pick whichever you find comfortable.

If you don't yet know how to use a tool like this to log in to a server or upload/download files, we've written a dedicated step-by-step tutorial — please read it first: Beginner tutorial: How to log in to a server and upload/download files with MobaXterm

For the command-line parts of the installation, in almost every case you only need to “copy + paste” the command rather than typing it out character by character. The reason is simple: typing commands manually makes it very easy to mistype a character — especially characters that look alike (e.g. the lowercase letter l and the digit 1 are easy to confuse). A single mistyped character can cause an error, or even unintended consequences. So this guide strongly recommends:

1. First select and copy the entire line of the command on the web page (Ctrl+C on Windows/Linux, Cmd+C on Mac)
2. Switch to your terminal window (e.g. the terminal in MobaXterm). For many terminal tools, simply right-clicking inside the terminal will automatically paste whatever you just copied (this is the default behavior in many terminal tools, including MobaXterm and xshell). If right-click doesn't paste, try Shift + Insert, or look for a “Paste” option in the terminal software's menu.
3. After pasting, press Enter to run it

Extremely important reminder: the part at the start of a command line that looks like [lxkt@localhost ~]$, or sometimes just a single $ / #, is called the “command prompt.” It is not part of the command itself — it's simply a symbol the terminal uses to indicate “I'm waiting for your input.” When copying a command, never copy the prompt along with it — only copy the actual command text that comes after the prompt. If you paste and run the prompt as if it were part of the command, the terminal will throw a “command not found” style error. This is a very common beginner mistake, so watch out for it.

In the installation docs you'll see commands that contain things like $(uname -r) and $USER, for example:

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

Here, $(uname -r) is part of the command — you do not need to, and should not, replace it with anything else (such as your own username). uname -r is a Linux system command whose job is to “query the version number of the currently running kernel,” and $(…) means “run the command inside the parentheses first, then substitute its result into the outer command.” So the whole command means “automatically find out my current kernel version, then install the development packages matching that version.” You only need to copy and paste the entire line exactly as it is — no modification needed.

Likewise, $USER that appears in commands is also a system variable that gets automatically substituted with your currently logged-in username — again, no manual editing required.

• In the command nvidia-smi, there's a hyphen - between nvidia and smi, and no space. Some people accidentally type “nvidia - smi” or “nvidia smi”, which produces a “command not found” error.
• Watch out for the difference between the lowercase letter l and the digit 1 — both appear in many commands and paths and look very similar.
• For the same reason: whenever you can copy-paste, do that instead of typing it manually.

Installing the GPU driver, Docker, and nvidia-container-toolkit all require root privileges (or sudo privileges) on the server. If you don't have this yourself, please ask your server administrator to grant you sudo access, or ask them to install these components for you following this guide.

1. The CPU must be x86_64 architecture
2. If you want to use the GPU version, the graphics card must be an NVIDIA card. Most mainstream compute GPUs on the market are supported, such as the 1080ti, 3080ti, 3090, 4090, 5090, etc. (or GPUs of an equivalent architecture). You can check GPU models and their corresponding architecture at GPU performance comparison.
3. We recommend 128GB of RAM or more; below 128GB you can only install it for a quick trial/test — it isn't suitable for actually running qflow computation jobs
4. The GPU driver on the host machine needs to support CUDA 12.1 or later (for the 1080ti, don't use a driver version above CUDA 12.8, or it may be incompatible)
5. This guide assumes your Linux workstation already has its operating system installed (CentOS 7.9 / Rocky 8.10 / Ubuntu 24.04 — newer versions generally work too), but doesn't yet have any PWstudio-related software installed
6. If you're on Windows, you'll need to install WSL first (a Linux subsystem for Windows) — see Windows 11 WSL2 installation or Windows 11 WSL2 CPU installation. Windows WSL currently only offers the CPU version.

Several installer packages used during installation (the NVIDIA driver, the Docker offline package, the nvidia-container-toolkit offline package, etc.) are provided as plain web links, which means you need to download them using a browser, rather than downloading them directly from the Linux server's command line (though if your server does have direct access to the outside internet, you can also download them directly with wget from the command line — the corresponding commands are given in the guide too).

If you download the installer packages using a browser on your own computer, you'll then need to upload those downloaded files to the Linux server before you can continue installing. This is exactly where the tools mentioned in section 0.3 (MobaXterm, WinSCP, etc.) come in — they let you both log in to the server's command line and drag-and-drop files to upload them. If you're not familiar with this yet, please read the MobaXterm beginner tutorial first.

1. Installing the graphics (GPU) driver, Docker, and nvidia-container-toolkit all require root privileges on the server.
2. We recommend installing on a GPU server running Linux — a personal Windows PC likely doesn't have enough compute power.

1. The CPU must be x86_64
2. The graphics card (GPU) must be NVIDIA; currently supported models include the 1080ti, 3080ti, 3090, 4090 D, 4090, etc.
3. We recommend 128GB of RAM or more; below 128GB you can only install it for testing purposes — it's not suitable for running qflow jobs

1. The host machine's GPU driver version needs to support CUDA 12.1 or later
2. For the 1080ti graphics card, the driver should not exceed CUDA 12.8

Check whether the server has a GPU: if the command produces output (a line containing the GPU model), the GPU was detected; if there's no output at all, the GPU wasn't detected, or the server simply doesn't have one installed.

lspci | grep -i nvidia

Check whether the GPU driver is installed and which version it is. If you see the GPU model, driver version, CUDA version, etc., the driver is already installed and you can skip the corresponding install step. If you see “nvidia-smi: command not found” (or “-bash: nvidia-smi: command not found”), the driver isn't installed yet and you'll need to install it following the chapters below.

nvidia-smi

Note: nvidia-smi is joined with a hyphen and has no space — typing it wrong easily results in “command not found,” so we recommend copying and pasting it directly.

• For CentOS/Rocky-family Linux, check the system version:

cat /etc/redhat-release

• For Ubuntu/Debian-family Linux, check the system version:

cat /etc/os-release

1. Use this page to find your system version
2. Decide for yourself whether you need the CPU version or the GPU version
3. Based on your system version and CPU/GPU choice, go to the corresponding chapter to install
4. If you run into problems during installation, check the FAQ chapter, or search using an AI tool
5. Use the PWstudio workflow function verification chapter to verify everything works
6. If you run into an issue, or have tips to share from your own installation, feel free to leave a comment on Issue Report

Summary (so you have a rough idea of the steps involved):

• CPU version: Install Docker → Install the license service → Start the container
• GPU version: Install the GPU driver → Install Docker → Install nvidia-container-toolkit → Install the license service → Start the container

Of the four or five steps above, if your machine already has the driver/Docker installed, you can skip the corresponding step. If this is your first time installing, going through every step (including a few system reboots, and downloading the roughly 12GB qflow image, which may take around 15 minutes) will take about 30 minutes to 1 hour in total, depending on your network speed and machine performance. Please be patient — it's not stuck, it just takes a while.