Running your own package mirror (such as for Proxmox products) may seem like an advanced setup, but it addresses challenges that are increasingly relevant in modern infrastructures. At its core, a mirror is simply a local copy of selected repositories, yet the advantages extend far beyond faster downloads. By keeping a local mirror, organizations can reduce external bandwidth usage because every server pulls packages from the same local source rather than repeatedly accessing the internet. This also ensures consistency across nodes, avoiding scenarios where some machines install slightly newer or different packages than others, which can lead to unpredictable behavior. Additionally, relying on a local mirror provides controlled availability; even if an external repository is temporarily down, your systems remain unaffected.
Security and compliance also benefit from a local mirror. Administrators can control which repositories and signing keys are trusted, reducing exposure to tampered or malicious sources. Snapshots of the repository can be frozen at specific points in time, allowing updates to be tested in staging environments before being deployed, creating an auditable and predictable update process. This also brings in some additional features, such like staging of packages from a synced repository which might come close to the enterprise repositories of Proxmox.
The importance of mirrors becomes even more pronounced in air-gapped environments, where systems have no direct access to the internet or public repositories. In such scenarios, a local mirror becomes the only source of packages and updates. Without it, administrators would be forced to manually transfer packages from external machines, risking inconsistency, human error, or outdated software. A well-maintained mirror in an air-gapped network ensures that updates, security patches, and dependencies are reliably available while preserving the isolation of the environment. Within this HowTo, we will now setup a mirror for the Proxmox non-enterprise / no-subscription repositories and serve them internally on our own domain and webserver with nginx.
Installation
The proxmox-offline-mirror package is a tool provided exclusively through the official Proxmox VE (PVE) repository. It allows users to create offline mirrors of Proxmox and Debian repositories, which is especially useful in air-gapped environments or when bandwidth limitations make online updates impractical. There are two main ways to install the package: directly on a Proxmox VE node, or on a Debian system by adding the PVE repository. The recommended approach is to use a Debian 13 (Trixie) system, which ensures compatibility and avoids conflicts with other repositories. /etc/apt/sources.list.d/proxmox.sources
Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
This configuration points your system to the Proxmox repository without requiring a subscription, and ensures package integrity with the provided GPG key. Afterwards, we can simply update the repository data and install the package proxmox-offline-mirror by running the following commands:
apt-get update ; apt install proxmox-offline-mirror
Once installed, the proxmox-offline-mirror command will be available on your system, ready to create offline mirrors for Proxmox VE and Debian repositories. This method allows you to prepare air-gapped environments efficiently or maintain local mirrors for multiple Proxmox installations. The next step is to prepare the directory structure for the mirrored repositories which can be placed anywhere. In this example, we use /var/lib/proxmox-offline-mirror/mirrors and mirror the following repositories (you can add/remove on your own):
o debian-trixie-security
o pve-no-subscription
The directories can simply be created this way:
mkdir -p /var/lib/proxmox-offline-mirror/mirrors/.pool
mkdir -p /var/lib/proxmox-offline-mirror/mirrors/debian-trixie-security
mkdir -p /var/lib/proxmox-offline-mirror/mirrors/pve-no-subscription
Configuration
One of the most important parts is to configure the /etc/proxmox-offline-mirror.cfg file, which holds the information of the mirrored repositories. This file allows us to mirror Debian based repositories in general - which can be a Debain upstream repository, but also the Proxmox pve-no-subscription repository. In case of a fully air-gapped environment, both ones might make sense to have in place and an example configuration could look like:
mirror: debian-trixie-security
architectures amd64
architectures all
base-dir /var/lib/proxmox-offline-mirror/mirrors
ignore-errors false
key-path /usr/share/keyrings/debian-archive-trixie-security-automatic.gpg
repository deb http://security.debian.org/debian-security trixie-security main contrib non-free non-free-firmware
skip-sections games
skip-sections debug
skip-sections graphics
skip-sections GNOME
skip-sections KDE
sync true
verify true
mirror: pve-no-subscription
architectures amd64
architectures all
base-dir /var/lib/proxmox-offline-mirror/mirrors
ignore-errors false
key-path /usr/share/keyrings/proxmox-archive-keyring.gpg
repository deb http://download.proxmox.com/debian/pve trixie pve-no-subscription
sync true
verify true
Make sure to copy over and include the GPG files and to adjust the key-paths.
Mirroring Repositories
After creating the configuration file of the mirrored repositories, we finally need to mirror and snapshot them.
proxmox-offline-mirror mirror snapshot create debian-trixie-security
proxmox-offline-mirror mirror snapshot create pve-no-subscription
This creates a directory below our recently created dir /var/lib/proxmox-offline-mirror/mirrors// including a timestamp which looks like 2025-08-26T19:43:34Z.
Hint:To make it the overall node managent easier and to avoid adjusting them for each snapshot, you might simply create a symlink like "latest" and switch that one to the latest snapshot.
Proxy Connection
proxmox-offline-mirror supports the use of HTTP/HTTPS proxies through environment variables, which makes it possible to operate in restricted network environments where direct internet access is not available. The tool relies on the environment variable ALL_PROXY to determine whether requests should be routed through a proxy.
When ALL_PROXY is set, all HTTP and HTTPS connections are routed through the specified HTTP proxy. At the moment, only HTTP proxies are supported. The proxy address must follow the format [http://][user:password@]
export ALL_PROXY=http://myuser:mypassword@proxy.example.com:8080
With this configuration, all connections made by proxmox-offline-mirror will be routed through the specified proxy server.
APT Web Repository with Nginx
Afterwards, we can start exposing the staged repositories by making them accessible via http/https by a webserver. In this case, we simply use nginx and since we are only serving already present static content, we can simply link the mirrored repositories to the default web root directory. For production cases, you might want to adjust nginx and also provide https connections.
apt-get -y install nginx
ln -s /var/lib/proxmox-offline-mirror/mirrors/ /var/www/html/mirror
The whole root directory containing all mirrored snapshots is now linked and can be used and accessed by remote clients by http/https.
PVE Nodes Adding the air-gapped Repository
Within the last step we need to make sure that our PVE nodes use our newly created repository mirror. Depending on which repositories we mirror, we need to add or adjust the apt sources. For this example, we only change and adjust the Proxmox sources in /etc/apt/sources.list.d/proxmox.sources. There, we can simply change the URIs part.
Types: deb
URIs: http://repo-pve.gyptazy.com/mirrors/pve-no-subscription/latest
Suites: trixie
Components: pve-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
Afterwards, we can update our sources including our recently added self-mirrored Proxmox (non-enterprise) repository:
root@pve01-test:/etc/apt/sources.list.d# apt-get update
Get:1 http://repo-pve.gyptazy.com/mirrors/pve-no-subscription/latest trixie InRelease [2,771 B]
Get:2 http://repo-pve.gyptazy.com/mirrors/pve-no-subscription/latest trixie/pve-no-subscription amd64 Packages [170 kB]
Hit:3 http://repo-pve.gyptazy.com/mirrors/debian-trixie-security/latest trixie-security InRelease
Fetched 173 kB in 0s (1,663 kB/s)
Reading package lists... Done
Conclusion
Creating an air-gapped offline repository mirror for Proxmox VE is surprisingly straightforward and can be accomplished quickly using the proxmox-offline-mirror tool. By following the steps outlined in this guide, organizations can ensure that their Proxmox nodes have a reliable, consistent, and secure source of packages and updates, even in environments with no internet access. This approach not only improves update consistency across nodes but also enables controlled testing and staging of packages before deployment.
It is important to note, however, that to access and mirror a product’s enterprise repository, proxmox-offline-mirror requires both an active product subscription key and a Proxmox Offline Mirror subscription. This can create potential conflicts for enterprises. While this guide demonstrates how to achieve a fully functional mirror based on the non-enterprise repository, organizations that purchase smaller or lower-tier subscriptions may find themselves limited in accessing the enterprise repository via offline mirroring. In practice, this means that some companies might end up using the non-enterprise repository even though they have a valid license, because offline mirroring of enterprise repositories is restricted to at least the Standard subscription.
From a business perspective, it is always recommended that enterprises obtain an official subscription. This not only ensures full access to enterprise repositories but also supports the developers maintaining and improving Proxmox VE. While the current behavior may seem inconsistent or geared toward upselling, it is possible that Proxmox may refine offline mirror access in the future, potentially offering additional ways to increase value for both users and the company. For now, this guide provides a practical method for setting up a non-enterprise offline mirror, which can serve most air-gapped or bandwidth-limited environments effectively.