github.com/hanks177/podman/v4@v4.1.3-0.20220613032544-16d90015bc83/docs/tutorials/podman-for-windows.md (about) 1 ![PODMAN logo](../../logo/podman-logo-source.svg) 2 3 Podman for Windows 4 ================== 5 6 While "containers are Linux," Podman also runs on Mac and Windows, where it 7 provides a native CLI and embeds a guest Linux system to launch your 8 containers. This guest is referred to as a Podman machine and is managed with 9 the `podman machine` command. On Windows, each Podman machine is backed by a 10 virtualized Windows System for Linux (WSLv2) distribution. The podman command 11 can be run directly from your Windows PowerShell (or CMD) prompt, where it 12 remotely communicates with the podman service running in the WSL environment. 13 Alternatively, you can access Podman directly from the WSL instance if you 14 prefer a Linux prompt and Linux tooling. In addition to command-line access, 15 Podman also listens for Docker API clients, supporting direct usage of 16 Docker-based tools and programmatic access from your language of choice. 17 18 Prerequisites 19 ------------- 20 21 Since Podman uses WSL, you need a recent release of Windows 10 or Windows 11. 22 On x64, WSL requires build 18362 or later, and 19041 or later is required for 23 arm64 systems. Internally, WSL uses virtualization, so your system must 24 support and have hardware virtualization enabled. If you are running Windows 25 on a VM, you must have a VM that supports nested virtualization. 26 27 It is also recommended to install the modern "Windows Terminal," which 28 provides a superior user experience to the standard PowerShell and CMD 29 prompts, as well as a WSL prompt, should you want it. 30 31 You can install it by searching the Windows Store or by running the following 32 `winget` command: 33 34 `winget install Microsoft.WindowsTerminal` 35 36 37 Installing Podman 38 ----------------- 39 40 Installing the Windows Podman client begins by downloading the Podman Windows 41 installer. The Windows installer is built with each Podman release and can be 42 downloaded from the official 43 [Github release page](https://github.com/containers/podman/releases). The 44 Windows installer file is named podman-v.#.#.#.msi, where the # symbols 45 represent the version number of Podman. Be sure to download a 4.1 or later 46 release for the capabilities discussed in this guide. 47 48 ![Installing Podman 4.1.0](podman-win-install.jpg) 49 50 Once downloaded, simply run the MSI file, and relaunch a new terminal. After 51 this point, podman.exe will be present on your PATH, and you will be able to run 52 the `podman machine init` command to create your first machine. 53 54 `PS C:\Users\User> podman machine init` 55 56 Automatic WSL Installation 57 -------------------------- 58 59 If WSL has not been installed on your system, the first machine init command 60 will prompt a dialog to begin an automated install. If accepted, this process 61 will install the necessary Windows components, restart the system, and after 62 login, relaunch the machine creation process in a terminal window. Be sure to 63 wait a minute or two for the relaunch to occur, as Windows has a delay before 64 executing startup items. Alternatively, you can decline automatic installation 65 and install WSL manually. However, this will require additional download and 66 setup time. 67 68 Machine Init Process 69 -------------------- 70 71 After WSL is installed, the init command will install a minimal installation 72 of Fedora, customizing it to run podman. 73 74 ``` 75 PS C:\Users\User> podman machine init 76 Extracting compressed file 77 Importing operating system into WSL (this may take 5+ minutes on a new WSL install)... 78 Installing packages (this will take a while)... 79 Complete! 80 Configuring system... 81 Generating public/private ed25519 key pair. 82 Your identification has been saved in podman-machine-default 83 Your public key has been saved in podman-machine-default.pub 84 The key fingerprint is: 85 SHA256:RGTGg2Q/LX7ijN+mzu8+BzcS3cEWP6Hir6pYllJtceA root@WINPC 86 Machine init complete 87 To start your machine run: 88 89 podman machine start 90 ``` 91 92 93 Starting Machine 94 ---------------- 95 96 After the machine init process completes, it can then be started and stopped 97 as desired: 98 99 ``` 100 PS C:\Users\User> podman machine start 101 102 Starting machine "podman-machine-default" 103 104 This machine is currently configured in rootless mode. If your containers 105 require root permissions (e.g. ports < 1024), or if you run into compatibility 106 issues with non-podman clients, you can switch using the following command: 107 108 podman machine set --rootful 109 110 API forwarding listening on: npipe:////./pipe/docker_engine 111 112 Docker API clients default to this address. You do not need to set DOCKER_HOST. 113 Machine "podman-machine-default" started successfully 114 ``` 115 116 First Podman Command 117 -------------------- 118 119 From this point on, podman commands operate similarly to how they would on 120 Linux. 121 122 For a quick working example with a small image, you can run the Linux date 123 command on PowerShell. 124 125 ``` 126 PS C:\Users\User> podman run ubi8-micro date 127 Thu May 5 21:56:42 UTC 2022 128 ``` 129 130 Port Forwarding 131 --------------- 132 133 Port forwarding also works as expected; ports will be bound against localhost 134 (127.0.0.1). Note: When running as rootless (the default), you must use a port 135 greater than 1023. See the Rooftull and Rootless section for more details. 136 137 To launch httpd, you can run: 138 139 ``` 140 PS C:\Users\User> podman run --rm -d -p 8080:80 --name httpd docker.io/library/httpd 141 f708641300564a6caf90c145e64cd852e76f77f6a41699478bb83a162dceada9 142 ``` 143 144 A curl command against localhost on the PowerShell prompt will return a 145 successful HTTP response: 146 147 ``` 148 PS C:\Users\User> curl http://localhost:8080/ -UseBasicParsing 149 150 StatusCode : 200 151 StatusDescription : OK 152 Content : <html><body><h1>It works!</h1></body></html> 153 ``` 154 155 As with Linux, to stop, run: 156 157 `podman stop httpd` 158 159 160 Using API Forwarding 161 -------------------- 162 163 API forwarding allows Docker API tools and clients to use podman as if it was 164 Docker. Provided there is no other service listening on the Docker API pipe; 165 no special settings will be required. 166 167 ``` 168 PS C:\Users\User> .\docker.exe run -it fedora echo "Hello Podman!" 169 Hello Podman! 170 ``` 171 172 Otherwise, after starting the machine, you will be notified of an environment 173 variable you can set for tools to point to podman. Alternatively, you can shut 174 down both the conflicting service and podman, then finally run `podman machine 175 start` to restart, which should grab the Docker API address. 176 177 178 ``` 179 Another process was listening on the default Docker API pipe address. 180 You can still connect Docker API clients by setting DOCKER HOST using the 181 following PowerShell command in your terminal session: 182 183 $Env:DOCKER_HOST = 'npipe:////./pipe/podman-machine-default' 184 185 Or in a classic CMD prompt: 186 187 set DOCKER_HOST = 'npipe:////./pipe/podman-machine-default' 188 189 Alternatively, terminate the other process and restart podman machine. 190 Machine "podman-machine-default" started successfully 191 192 PS C:\Users\User> $Env:DOCKER_HOST = 'npipe:////./pipe/podman-machine-default' 193 PS C:\Users\User>.\docker.exe version --format '{{(index .Server.Components 0).Name}}' 194 Podman Engine 195 ``` 196 197 Rootfull & Rootless 198 ------------------- 199 200 On the embedded WSL Linux distro, podman can either be run under the root user 201 (rootful) or a non-privileged user (rootless). For behavioral consistency with 202 Podman on Linux, rootless is the default. Note: Rootfull and Rootless 203 containers are distinct and isolated from one another. Podman commands against 204 one (e.g., podman ps) will not represent results/state for the other. 205 206 While most containers run fine in a rootless setting, you may find a case 207 where the container only functions with root privileges. If this is the case, 208 you can switch the machine to rootful by stopping it and using the set 209 command: 210 211 ``` 212 podman machine stop 213 podman machine set --rootful 214 ``` 215 216 To restore rootless execution, set rootful to false: 217 218 ``` 219 Podman machine stop 220 Podman machine set --rootful=false 221 ``` 222 223 Another case in which you may wish to use rootful execution is binding a port 224 less than 1024. However, future versions of podman will likely drop this to a 225 lower number to improve compatibility with defaults on system port services (such 226 as MySQL) 227 228 Volume Mounting 229 --------------- 230 231 New in Podman v4.1 is the ability to perform volume mounts from Windows paths into a 232 Linux container. This supports several notation schemes, including: 233 234 Windows Style Paths: 235 236 `podman run --rm -v c:\Users\User\myfolder:/myfolder ubi8-micro ls /myfolder` 237 238 Unixy Windows Paths: 239 240 `podman run --rm -v /c/Users/User/myfolder:/myfolder ubi8-micro ls /myfolder` 241 242 Linux paths local to the WSL filesystem: 243 244 `podman run --rm -v /var/myfolder:/myfolder ubi-micro ls /myfolder` 245 246 All of the above conventions work, whether running on a Windows prompt or the 247 WSL Linux shell. Although when using Windows paths on Linux, appropriately quote 248 or escape the Windows path portion of the argument. 249 250 251 Listing Podman Machine(s) 252 ------------------------- 253 254 To list the available podman machine instances and their current resource 255 usage, use the `podman machine ls` command: 256 257 ``` 258 PS C:\Users\User> podman machine ls 259 260 261 NAME VM TYPE CREATED LAST UP CPUS MEMORY DISK SIZE 262 podman-machine-default wsl 2 hours ago Currently running 4 331.1MB 768MB 263 ``` 264 265 Since WSL shares the same virtual machine and Linux kernel across multiple 266 distributions, the CPU and Memory values represent the total resources shared 267 across running systems. The opposite applies to the Disk value. It is 268 independent and represents the amount of storage for each individual 269 distribution. 270 271 272 Accessing the Podman Linux Environment 273 -------------------------------------- 274 275 While using the podman.exe client on the Windows environment provides a 276 seamless native experience supporting the usage of local desktop tools and 277 APIs, there are a few scenarios in which you may wish to access the Linux 278 environment: 279 280 + Updating to the latest stable packages on the embedded Fedora instance 281 + Using Linux development tools directly 282 + Using a workflow that relies on EXT4 filesystem performance or behavior 283 semantics 284 285 There are three mechanisms to access the embedded WSL distribution: 286 1. SSH using `podman machine ssh` 287 2. WSL command on the Windows PowerShell prompt 288 3. Windows Terminal Integration 289 290 ### Using SSH 291 292 SSH access provides a similar experience as Podman on Mac. It immediately 293 drops you into the appropriate user based on your machine's rootful/rootless 294 configuration (root in the former, 'user' in the latter). The --username 295 option can be used to override with a specific user. 296 297 An example task using SSH is updating your Linux environment to pull down the 298 latest OS bugfixes: 299 300 `podman machine ssh sudo dnf upgrade -y` 301 302 ### Using the WSL Command 303 304 The `wsl` command provides direct access to the Linux system but enters the 305 shell as root first. This is due to design limitations of WSL, where running 306 systemd (Linux's system services) requires the usage of a privileged process 307 namespace. 308 309 Unless you have no other distributions of WSL installed, it's recommended to 310 use the `-d` option with the name of your podman machine (podman-machine-default 311 is the default) 312 313 ``` 314 PS C:\Users\User> wsl -d podman-machine-default 315 ``` 316 317 You will be automatically entered into a nested process namespace where 318 systemd is running. If you need to access the parent namespace, hit `ctrl-d` 319 or type exit. This also means to log out, you need to exit twice. 320 321 ``` 322 [root@WINPC /]# podman --version 323 podman version 4.1.0 324 ``` 325 326 327 To access commands as the non-privileged user (rootless podman), you must 328 first type `su user`. Alternatively, you can prefix the `wsl` command to use the 329 special `enterns`: 330 331 ``` 332 wsl -d podman-machine-default enterns su user 333 [user@WINPC /]$ id 334 uid=1000(user) gid=1000(user) groups=1000(user),10(wheel) 335 ``` 336 337 Likewise, running commands as root without entering a prompt should also be 338 prefixed with `enterns`. 339 340 `wsl -d podman-machine-default enterns systemctl status` 341 342 Accessing the WSL instance as a specific user using `wsl -u` or using inline 343 commands without `enterns` is not recommended since commands will execute 344 against the incorrect namespace. 345 346 ### Using Windows Terminal Integration 347 348 Entering WSL as root is a 2-click operation. Simply click the drop-down tag, 349 and pick 'podman-machine-default,' where you will be entered directly as root. 350 351 ![Using WSL in Windows Terminal](podman-wsl-term.jpg) 352 353 As before, to switch to a non-privileged user for rootless podman commands, 354 type `su user`. 355 356 ``` 357 [root@WINPC /]# su user 358 [user@WINPC /]$ podman info --format '{{.Store.RunRoot}}' 359 /run/user/1000/containers 360 ``` 361 362 Stopping a Podman Machine 363 ------------------------- 364 365 To stop a running podman machine, use the `podman machine stop` command: 366 367 ``` 368 PS C:\Users\User> podman machine stop 369 Machine "podman-machine-default" stopped successfully 370 ``` 371 372 Removing a Podman Machine 373 ------------------------- 374 375 To remove a machine, use the `podman machine rm` command: 376 377 ``` 378 PS C:\Users\User> podman machine rm 379 380 The following files will be deleted: 381 382 C:\Users\User\.ssh\podman-machine-default 383 C:\Users\User\.ssh\podman-machine-default.pub 384 C:\Users\User\.local\share\containers\podman\machine\wsl\podman-machine-default_fedora-35-x86_64.tar 385 C:\Users\User\.config\containers\podman\machine\wsl\podman-machine-default.json 386 C:\Users\User\.local\share\containers\podman\machine\wsl\wsldist\podman-machine-default 387 388 389 Are you sure you want to continue? [y/N] y 390 ``` 391 392 393 394 Troubleshooting 395 --------------- 396 397 Recovering from a failed auto-installation of WSL 398 399 If auto-install fails and retrying is unsuccessful, you can attempt to reset 400 your WSL system state and perform a manual WSL installation using the `wsl 401 --install command`. To do so, perform the following steps: 402 403 1. Launch PowerShell as administrator 404 ``` 405 Start-Process powershell -Verb RunAs 406 ``` 407 2. Disable WSL Features 408 ``` 409 dism.exe /online /disable-feature /featurename:Microsoft-Windows-Subsystem-Linux /norestart 410 dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /norestart 411 ``` 412 3. Reboot 413 4. Run manual WSL install 414 ``` 415 wsl --install 416 ``` 417 5. Continue with podman machine init