You've got a config file, a backup archive, or an installer sitting on your desktop, and it needs to end up inside a VM or container running on your Proxmox VE host. Sounds simple. Then you actually try it and realize there's no drag-and-drop between your laptop and the web console, and the "obvious" answer depends entirely on whether you're dealing with a VM or an LXC container.

The two aren't interchangeable here. A container shares the host's kernel, so Proxmox can reach directly into its filesystem from the outside. A VM is a fully isolated machine with its own kernel, so the host has no such shortcut — you're stuck going through the network, just like you would with any other remote computer. Once you know which situation you're in, the right tool becomes obvious.

This guide covers both paths: the two built-in pct commands that work for containers, and the handful of methods — SCP, a mounted ISO, and virtiofs — that actually work for VMs.

What You Will Learn

  • Why containers and VMs need completely different file-copy methods
  • How to use pct push and pct pull to move single files in and out of an LXC container
  • How to copy a whole directory into a container when pct push won't do it alone
  • How to get files into a VM over SCP, and what to do when there's no network yet
  • How to set up a permanent shared folder between the host and a VM with virtiofs
  • The errors people hit most often with each method, and how to fix them

What Is This Feature?

pct push and pct pull are commands built into Proxmox VE's container management tool, pct. They copy a single file between the Proxmox host and a running or stopped LXC container. An LXC container (Linux Container) is a lightweight virtualized environment that shares the host's Linux kernel instead of running its own — that's what makes pct push possible in the first place: the host can literally reach into the container's files on disk.

A VM (virtual machine) is different. It runs its own complete operating system and kernel, fully separated from the host, the same way a physical computer would be. There's no equivalent "reach in and drop a file" command for VMs in Proxmox, because from the host's point of view, a VM's disk is just an opaque virtual hard drive image. To get a file inside, you go through the VM's network stack instead — typically with SCP (Secure Copy), which rides on top of SSH.

Proxmox also supports virtiofs, a shared-filesystem feature that lets a VM mount a folder from the host directly, without going over the network at all. It's a newer option and it comes with some real trade-offs, which we'll get to.

Why Would You Use It?

A few situations come up constantly once you're running anything beyond a single test VM:

  • Dropping a docker-compose.yml or an app config into a fresh LXC container right after you create it
  • Pulling a log file or database dump out of a container to look at locally, without SSHing in and cat-ing the whole thing to your terminal
  • Getting a driver package or installer into a Windows VM that isn't on the network yet
  • Sharing a folder of media, documents, or build artifacts between your Proxmox host and a VM on an ongoing basis

None of this is hard once you know which tool applies where. The frustrating part is when you try to use a container trick on a VM (or vice versa) and it just doesn't work — not because you did anything wrong, but because the two are architecturally different things.

Prerequisites

  • A Proxmox VE 8.x or 9.x host with at least one running container or VM
  • Root shell access to the Proxmox host, either through the web UI's >_ Shell button or SSH
  • For the VM method: SSH already enabled and reachable inside the guest OS. If you haven't set that up yet, it's worth doing first — this guide assumes it's already working
  • For virtiofs: a Linux VM with kernel 5.4 or newer (most modern distributions qualify by default)

You don't need anything installed on the Proxmox host beyond what ships by default. pct, qm, and scp are all there out of the box.

Step-by-Step Tutorial

1. Copy a single file into an LXC container

Open a shell on the Proxmox host and run:

pct push 105 /root/nginx.conf /etc/nginx/nginx.conf

Here, 105 is the container's VMID (find it in the left-hand tree in the web UI), the second path is the file's location on the Proxmox host, and the third is where it should land inside the container. The container can be running or stopped — it doesn't matter for pct push.

2. Set ownership while you're at it

If the file needs to belong to a specific user inside the container, don't push it and then chown it separately — just do both in one step:

pct push 105 /root/app.env /opt/myapp/.env --user appuser --group appuser --perms 0640

The user and group have to already exist inside the container, or the command fails. Permissions are octal, same as chmod.

3. Pull a file out of a container

Going the other direction uses the same pattern, just reversed:

pct pull 105 /var/log/app/error.log /root/container105-error.log

This grabs /var/log/app/error.log from inside container 105 and saves it to the host at /root/container105-error.log. Useful for grabbing a log or config without opening a full shell session.

4. Copy a whole directory into a container

This is where people get tripped up: pct push only takes one file at a time, not a folder. For a directory, archive it first, push the archive, then unpack it inside the container:

tar czf /root/site.tar.gz -C /root/website .
pct push 105 /root/site.tar.gz /tmp/site.tar.gz
pct exec 105 -- tar xzf /tmp/site.tar.gz -C /var/www/html

pct exec runs a command inside the container from the host, so that last line extracts the archive without you needing to open a separate shell session into the container first. Clean up /tmp/site.tar.gz inside the container afterward if you don't want it hanging around.

5. Copy a file into a VM over SCP

Since a VM is reachable over the network like any other machine, this is standard SCP, run from wherever you're sitting — your laptop, or the Proxmox host itself:

scp ./installer.exe user@192.168.1.50:/home/user/

Replace the IP with the VM's actual address (check it under the VM's Summary tab in the web UI, assuming the QEMU Guest Agent is installed — otherwise check your router's DHCP leases). This works for Linux VMs out of the box. Windows VMs need an SSH server running first; OpenSSH Server is a built-in optional feature on Windows 10 and 11 you can turn on from Settings > Apps > Optional Features, or with WinSCP as a GUI alternative if you'd rather not touch a Windows SSH server at all.

6. Get a file into a VM that has no network yet

Fresh VMs mid-install, or ones you're deliberately keeping offline, don't have this option. Build a small ISO with the files you need and attach it as a virtual CD instead:

genisoimage -o /root/transfer.iso -J -R /root/files-to-send/

-J and -R add Joliet and Rock Ridge extensions so the filenames survive being read by both Windows and Linux guests. Upload the resulting transfer.iso to your Proxmox storage the same way you'd upload a normal install ISO, then attach it to the VM as a second CD/DVD drive under Hardware > Add > CD/DVD Drive. It shows up as a normal optical disc inside the guest, files and all.

7. Set up a persistent shared folder with virtiofs

If you're going to be moving files between the host and one particular VM regularly, virtiofs beats doing an SCP transfer every time. First, map the host directory:

pvesh create /cluster/mapping/dir --id shareddata --map node=pve1,path=/mnt/shared-data

Then add the share to the VM's configuration:

qm set 110 --virtiofs0 shareddata

Inside a Linux guest, mount it with:

mount -t virtiofs shareddata /mnt/shared

Add that mount line to /etc/fstab if you want it to survive a reboot. One catch worth knowing before you commit to this: VMs with a virtiofs share attached can't use memory hotplug, live migration, snapshots, or hibernation. For a VM you migrate between nodes or snapshot regularly, that's a dealbreaker. For a single-node homelab VM, it usually isn't.

Commands Explained

CommandWhat it does
pct push <vmid> <file> <dest>Copies one file from the Proxmox host into a container
pct pull <vmid> <path> <dest>Copies one file from a container back to the Proxmox host
pct exec <vmid> -- <cmd>Runs a command inside a container from the host shell, without a full login session
scp source user@host:destCopies a file over SSH to any reachable machine, including a VM with an IP address
qm set <vmid> --virtiofsN <dirid>Attaches a host directory mapping to a VM as a virtiofs share
pvesh create /cluster/mapping/dirRegisters a host folder as a named, reusable directory mapping for virtiofs or PCI/USB passthrough-style resource mapping

Common Errors

"unable to open file - No such file or directory" from pct push. Almost always a typo in the source path on the host side, not the container side. Double-check the file actually exists where you think it does with a quick ls before running the command again.

pct push succeeds but the app inside the container can't read the file. The file landed with root ownership, and your application runs as a different user. This is exactly what the --user and --group flags are for — use them up front instead of chowning after the fact.

"scp: /home/user/: No such file or directory" even though the directory clearly exists in the guest. Nine times out of ten this means the username in the SCP command doesn't match a real account on that VM, and SSH is quietly authenticating you into the wrong home directory (or failing before it gets that far). Confirm the username first with a plain ssh user@host login.

"Connection refused" on port 22 when you try to SCP into a VM. The SSH server isn't running yet, or the VM's firewall (or Proxmox's own firewall, if you've enabled it on that VM) is blocking the port. Check systemctl status ssh inside the guest before anything else.

"mount: unknown filesystem type 'virtiofs'" inside the guest. The VM's kernel is older than 5.4, or the guest doesn't include virtiofs support at all. Update the guest kernel, or fall back to SCP for that VM.

Troubleshooting

If pct push hangs instead of failing outright, check whether the container is in the middle of starting up or shutting down. Give it a few seconds and try again once pct status 105 shows a stable state.

For SCP transfers that start and then stall partway through, it's usually a network MTU mismatch rather than anything wrong with SCP itself — this shows up more on VLAN-tagged or SDN-managed bridges than on a plain default bridge. Try the transfer again with scp -l 8192 to cap the bandwidth and see if that's actually the issue, or check dmesg on the guest for fragmentation errors.

If a virtiofs mount fails with a permission error rather than a missing filesystem type, check the ownership and permissions on the host-side directory itself. Virtiofs respects the host's file permissions by default, so a folder that's 700 and owned by root on the host will look exactly that locked-down from inside the guest too.

Best Practices

  • For anything you'll do more than once, set up SSH keys instead of typing a password every time — ssh-copy-id user@vm-ip takes thirty seconds and saves you from typing passwords for the rest of the VM's life.
  • Don't leave transfer ISOs attached to VMs after you're done with them. They take up a CD/DVD slot and occasionally confuse a guest's boot order if you're not paying attention.
  • Use pct push --perms for anything security-sensitive, like SSH keys or API tokens, instead of pushing with default permissions and fixing them in a second step you might forget.
  • Reach for virtiofs only when you genuinely need an ongoing shared folder. If it's a one-time transfer, SCP or pct push is simpler and doesn't cost you snapshots and live migration.

Frequently Asked Questions

Can I use pct push and pct pull while the container is running?

Yes. Both commands work on running and stopped containers equally.

Is there a qm equivalent of pct push for VMs?

No. The qm command can run guest-agent commands like qm guest exec for executing programs inside a VM, but there's no built-in file-copy command for VMs. SCP, a mounted ISO, or virtiofs are the actual options.

Can I copy files between two containers directly?

Not in one step. Pull the file out to the Proxmox host with pct pull, then push it into the second container with pct push.

Does the QEMU Guest Agent let me transfer files into a VM?

Not through the qm CLI. The guest agent handles things like reporting the VM's IP address and shutting it down cleanly, but Proxmox doesn't expose a file-transfer wrapper around it — SCP is still the standard route for VMs.

Is virtiofs safe to use on a VM I plan to live-migrate later?

No. Live migration, snapshots, hibernation, and memory hotplug are all disabled on a VM with a virtiofs share attached. Remove the share first if you need any of those features back.

Conclusion

Containers and VMs need different tools here for the same reason they behave differently everywhere else: one shares the host's kernel and one doesn't. pct push and pct pull cover containers in a single command each. For VMs, SCP handles the common case once networking is up, a small ISO covers the rare offline case, and virtiofs is there if you need a folder that stays mounted permanently and you're willing to trade away live migration for it.

None of these are things you'll use every day, but they're exactly the kind of small, unglamorous tasks that eat twenty minutes of confused searching if you don't already know which one applies to your situation.