podman-volume-create(1) General Commands Manual podman-volume-create(1)
NAME
podman-volume-create - Create a new volume
SYNOPSIS
podman volume create [options] [name]
DESCRIPTION
Creates an empty volume and prepares it to be used by containers. The
volume can be created with a specific name, if a name is not given a
random name is generated. You can add metadata to the volume by using
the --label flag and driver options can be set using the --opt flag.
OPTIONS
--driver, -d=driver
Specify the volume driver name (default local). There are two drivers
supported by Podman itself: local and image.
The local driver uses a directory on disk as the backend by default, but
can also use the mount(8) command to mount a filesystem as the volume if
--opt is specified.
The image driver uses an image as the backing store of for the volume.
An overlay filesystem is created, which allows changes to the volume to
be committed as a new layer on top of the image.
Using a value other than local or image, Podman attempts to create the
volume using a volume plugin with the given name. Such plugins must be
defined in the volume_plugins section of the containers.conf(5) configu-
ration file.
--help
Print usage statement
--ignore
Don't fail if the named volume already exists, instead just print the
name. Note that the new options are not applied to the existing volume.
--label, -l=label
Set metadata for a volume (e.g., --label mykey=value).
--opt, -o=option
Set driver specific options. For the default driver, local, this allows
a volume to be configured to mount a filesystem on the host.
For the local driver the following options are supported: type, device,
o, and [no]copy.
• The type option sets the type of the filesystem to be mounted,
and is equivalent to the -t flag to mount(8).
• The device option sets the device to be mounted, and is equiva-
lent to the device argument to mount(8).
• The copy option enables copying files from the container image
path where the mount is created to the newly created volume on
the first run. copy is the default.
The o option sets options for the mount, and is equivalent to the
filesystem options (also -o) passed to mount(8) with the following ex-
ceptions:
• The o option supports uid and gid options to set the UID and
GID of the created volume that are not normally supported by
mount(8).
• The o option supports the size option to set the maximum size
of the created volume, the inodes option to set the maximum
number of inodes for the volume, and noquota to completely dis-
able quota support even for tracking of disk usage. The size
option is supported on the "tmpfs" and "xfs[note]" file sys-
tems. The inodes option is supported on the "xfs[note]" file
systems. Note: xfs filesystems must be mounted with the pr-
jquota flag described in the xfs_quota(8) man page. Podman will
throw an error if they're not.
• The o option supports using volume options other than the
UID/GID options with the local driver and requires root privi-
leges.
• The o options supports the timeout option which allows users to
set a driver specific timeout in seconds before volume creation
fails. For example, --opt=o=timeout=10 sets a driver timeout of
10 seconds.
Note Do not confuse the --opt,-o create option with the -o mount option.
For example, with podman volume create, use -o=o=uid=1000 not
-o=uid=1000.
For the image driver, the only supported option is image, which speci-
fies the image the volume is based on. This option is mandatory when
using the image driver.
When not using the local and image drivers, the given options are passed
directly to the volume plugin. In this case, supported options are dic-
tated by the plugin in question, not Podman.
EXAMPLES
Create empty volume.
$ podman volume create
Create empty named volume.
$ podman volume create myvol
Create empty named volume with specified label.
$ podman volume create --label foo=bar myvol
Create tmpfs named volume with specified size and mount options.
# podman volume create --opt device=tmpfs --opt type=tmpfs --opt o=size=2M,nodev,noexec myvol
Create tmpfs named volume testvol with specified options.
# podman volume create --opt device=tmpfs --opt type=tmpfs --opt o=uid=1000,gid=1000 testvol
Create image named volume using the specified local image in contain-
ers/storage.
# podman volume create --driver image --opt image=fedora:latest fedoraVol
QUOTAS
podman volume create uses XFS project quota controls for controlling the
size and the number of inodes of builtin volumes. The directory used to
store the volumes must be an XFS file system and be mounted with the
pquota option.
Example /etc/fstab entry:
/dev/podman/podman-var /var xfs defaults,x-systemd.device-timeout=0,pquota 1 2
Podman generates project IDs for each builtin volume, but these project
IDs need to be unique for the XFS file system. These project IDs by de-
fault are generated randomly, with a potential for overlap with other
quotas on the same file system.
The xfs_quota tool can be used to assign a project ID to the storage
driver directory, e.g.:
echo 100000:/var/lib/containers/storage/overlay >> /etc/projects
echo 200000:/var/lib/containers/storage/volumes >> /etc/projects
echo storage:100000 >> /etc/projid
echo volumes:200000 >> /etc/projid
xfs_quota -x -c 'project -s storage volumes' /<xfs mount point>
In the example above we are configuring the overlay storage driver for
newly created containers as well as volumes to use project IDs with a
start offset. All containers are assigned larger project IDs (e.g. >=
100000). All volume assigned project IDs larger project IDs starting
with 200000. This prevents xfs_quota management conflicts with contain-
ers/storage.
MOUNT EXAMPLES
podman volume create allows the type, device, and o options to be passed
to mount(8) when using the local driver.
s3fs-fuse
s3fs-fuse or just s3fs, is a fuse filesystem that allows s3 prefixes to
be mounted as filesystem mounts.
Installing:
$ doas dnf install s3fs-fuse
Simple usage:
$ s3fs --help
$ s3fs -o use_xattr,endpoint=aq-central-1 bucket:/prefix /mnt
Equivalent through mount(8)
$ mount -t fuse.s3fs -o use_xattr,endpoint=aq-central-1 bucket:/prefix /mnt
Equivalent through podman volume create
$ podman volume create s3fs-fuse-volume -o type=fuse.s3fs -o device=bucket:/prefix -o o=use_xattr,endpoint=aq-central-1
The volume can then be mounted in a container with
$ podman run -v s3fs-fuse-volume:/s3:z --rm -it fedora:latest
Please see the available options on their wiki.
Using with other container users
The above example works because the volume is mounted as the host user
and inside the container root is mapped to the user in the host.
If the mount is accessed by a different user inside the container, a
"Permission denied" error will be raised.
$ podman run --user bin:bin -v s3fs-fuse-volume:/s3:z,U --rm -it fedora:latest
$ ls /s3
# ls: /s3: Permission denied
In FUSE-land, mounts are protected for the user who mounted them; spec-
ify the allow_other mount option if other users need access. > Note:
This will remove the normal fuse security measures on the mount point,
after which, the normal filesystem permissions will have to protect it
$ podman volume create s3fs-fuse-other-volume -o type=fuse.s3fs -o device=bucket:/prefix -o o=allow_other,use_xattr,endpoint=aq-central-1
$ podman run --user bin:bin -v s3fs-fuse-volume:/s3:z,U --rm -it fedora:latest
$ ls /s3
The Prefix must exist
s3fs will fail to mount if the prefix does not exist in the bucket.
Create a s3-directory by putting an empty object at the desired prefix/
key
$ aws s3api put-object --bucket bucket --key prefix/
If performance is the priority, please check out the more performant
goofys.
FUSE filesystems exist for Google Cloud Storage and Azure Blob
Storage
SEE ALSO
podman(1), containers.conf(5), podman-volume(1), mount(8), xfs_quota(8),
xfs_quota(8), projects(5), projid(5)
HISTORY
January 2020, updated with information on volume plugins by Matthew Heon
mheon@redhat.com ⟨mailto:mheon@redhat.com⟩ November 2018, Originally
compiled by Urvashi Mohnani umohnani@redhat.com ⟨mailto:umohnani@red-
hat.com⟩
podman-volume-create(1)
Generated by dwww version 1.16 on Tue Dec 16 06:02:24 CET 2025.