podman-machine-init(1) General Commands Manual podman-machine-init(1)
NAME
podman-machine-init - Initialize a new virtual machine
SYNOPSIS
podman machine init [options] [name]
DESCRIPTION
Initialize a new virtual machine for Podman.
The default machine name is podman-machine-default. If a machine name is
not specified as an argument, then the new machine will be named podman-
machine-default.
Rootless only.
Podman on MacOS and Windows requires a virtual machine. This is because
containers are Linux - containers do not run on any other OS because
containers' core functionality are tied to the Linux kernel. Podman ma-
chine must be used to manage MacOS and Windows machines, but can be op-
tionally used on Linux.
podman machine init initializes a new Linux virtual machine where con-
tainers are run. SSH keys are automatically generated to access the VM,
and system connections to the root account and a user account inside the
VM are added.
By default, the VM distribution is Fedora CoreOS except for WSL which is
based on a custom Fedora image. While Fedora CoreOS upgrades come out
every 14 days, the automatic update mechanism Zincata is disabled by
Podman machine.
To check if there is an upgrade available for your machine os, you can
run the following command:
$ podman machine ssh 'sudo rpm-ostree upgrade --check'
If an update is available, you can rerun the above command and remove
the --check and your operating system will be updated. After updating,
you must stop and start your machine with podman machine stop && podman
machine start for it to take effect.
Note: Updating as described above can result in version mismatches be-
tween Podman on the host and Podman in the machine. Executing podman
info should reveal versions of both. A configuration where the Podman
host and machine mismatch are unsupported.
For more information on updates and advanced configuration, see the Fe-
dora CoreOS documentation about auto-updates and update strategies.
Fedora CoreOS upgrades come out every 14 days and are detected and in-
stalled automatically. The VM is rebooted during the upgrade. For more
information on updates and advanced configuration, see the Fedora CoreOS
documentation about auto-updates and update strategies.
Default Podman machine settings can be set via the [machine] section in
the containers.conf(5) file.
OPTIONS
--cpus=number
Number of CPUs.
--disk-size=number
Size of the disk for the guest VM in GiB.
--help
Print usage statement.
--ignition-path
Fully qualified path of the ignition file.
If an ignition file is provided, the file is copied into the user's
CONF_DIR and renamed. Additionally, no SSH keys are generated, nor are
any system connections made. It is assumed that the user does these
things manually or handled otherwise.
--image
Fully qualified registry, path, or URL to a VM image. Registry target
must be in the form of docker://registry/repo/image:version.
Note: Only images provided by podman will be supported.
--memory, -m=number
Memory (in MiB). Note: 1024MiB = 1GiB.
--now
Start the virtual machine immediately after it has been initialized.
--playbook
Add the provided Ansible playbook to the machine and execute it after
the first boot.
Note: The playbook will be executed with the same privileges given to
the user in the virtual machine. The playbook provided cannot include
other files from the host system, as they will not be copied. Use of
the --playbook flag will require the image to include Ansible. The de-
fault image provided will have Ansible included.
--rootful
Whether this machine prefers rootful (true) or rootless (false) con-
tainer execution. This option determines the remote connection default
if there is no existing remote connection configurations.
API forwarding, if available, follows this setting.
--timezone
Set the timezone for the machine and containers. Valid values are local
or a timezone such as America/Chicago. A value of local, which is the
default, means to use the timezone of the machine host.
The timezone setting is not used with WSL. WSL automatically sets the
timezone to the same as the host Windows operating system.
--usb=bus=number,devnum=number or vendor=hexadecimal,product=hexadecimal
Assign a USB device from the host to the VM via USB passthrough. Only
supported for QEMU Machines.
The device needs to have proper permissions in order to be passed to the
machine. This means the device needs to be under your user group.
Note that using bus and device number are simpler but the values can
change every boot or when the device is unplugged.
When specifying a USB using vendor and product ID's, if more than one
device has the same vendor and product ID, the first available device is
assigned.
--user-mode-networking
Indicates that this machine relays traffic from the guest through a
user-space process running on the host. In some VPN configurations the
VPN may drop traffic from alternate network interfaces, including VM
network devices. By enabling user-mode networking (a setting of true),
VPNs observe all podman machine traffic as coming from the host, bypass-
ing the problem.
When the qemu backend is used (Linux, Mac), user-mode networking is
mandatory and the only allowed value is true. In contrast, The Win-
dows/WSL backend defaults to false, and follows the standard WSL network
setup. Changing this setting to true on Windows/WSL informs Podman to
replace the WSL networking setup on start of this machine instance with
a user-mode networking distribution. Since WSL shares the same kernel
across distributions, all other running distributions reuses this net-
work. Likewise, when the last machine instance with a true setting
stops, the original networking setup is restored.
--username
Username to use for executing commands in remote VM. Default value is
core for FCOS and user for Fedora (default on Windows hosts). Should
match the one used inside the resulting VM image.
--volume, -v=source:target[:options]
Mounts a volume from source to target.
Create a mount. If /host-dir:/machine-dir is specified as the
*source:target*, Podman mounts host-dir in the host to machine-dir in
the Podman machine.
Additional options may be specified as a comma-separated string. Recog-
nized options are: * ro: mount volume read-only * rw: mount volume
read/write (default) * security_model=[model]: specify 9p security model
(see below)
The 9p security model [determines] https://wiki.qemu.org/Documenta-
tion/9psetup#Starting_the_Guest_directly if and how the 9p filesystem
translates some filesystem operations before actual storage on the host.
In order to allow symlinks to work, on MacOS the default security model
is
none.
The value of mapped-xattr specifies that 9p store symlinks and some file
attributes as extended attributes on the host. This is suitable when the
host and the guest do not need to interoperate on the shared filesystem,
but has caveats for actual shared access; notably, symlinks on the host
are not usable on the guest and vice versa. If interoperability is re-
quired, then choose none instead, but keep in mind that the guest is not
able to do things that the user running the virtual machine cannot do,
e.g. create files owned by another user. Using none is almost certainly
the best choice for read-only volumes.
Example: -v "$HOME/git:$HOME/git:ro,security_model=none"
Default volume mounts are defined in containers.conf. Unless changed,
the default values is $HOME:$HOME.
Note on Windows Subsystem for Linux (WSL) Since all drives are mounted
at /mnt on startup by default in WSL, passing --volume is redundant and
has no effect. The host home directory for a C: drive will be mounted at
/mnt/c/Users/<my username>.
EXAMPLES
Initialize the default Podman machine, pulling the content from the in-
ternet.
$ podman machine init
Initialize a Podman machine for the specified name pulling the content
from the internet.
$ podman machine init myvm
Initialize the default Podman machine pulling the content from the in-
ternet defaulting to rootful mode. The default is rootless.
$ podman machine init --rootful
Initialize the default Podman machine overriding its disk size override,
pulling the content from the internet.
$ podman machine init --disk-size 50
Initialize the specified Podman machine overriding its memory size,
pulling the content from the internet.
$ podman machine init --memory=1024 myvm
Initialize the default Podman machine with the host directory /Users
mounted into the VM at /Users.
$ podman machine init -v /Users:/Users
Initialize the default Podman machine with a usb device passthrough
specified with options. Only supported for QEMU Machines.
$ podman machine init --usb vendor=13d3,product=5406
Initialize the default Podman machine with a usb device passthrough with
specified with options. Only supported for QEMU Machines.
$ podman machine init --usb bus=1,devnum=3
SEE ALSO
podman(1), podman-machine(1), containers.conf(5)
HISTORY
March 2021, Originally compiled by Ashley Cui acui@redhat.com
⟨mailto:acui@redhat.com⟩
podman-machine-init(1)
Generated by dwww version 1.16 on Tue Dec 16 06:20:36 CET 2025.