3x-uiInstallation
Install 3x-ui via the official script (stable, pinned, or dev-latest), unattended/cloud-init, or Docker — and choose SQLite or PostgreSQL.
3x-ui runs on a wide range of Linux distributions — Ubuntu, Debian, Armbian,
Fedora, CentOS, RHEL, AlmaLinux, Rocky Linux, Oracle Linux, Amazon Linux,
Virtuozzo, Arch, Manjaro, openSUSE (Tumbleweed/Leap), Alpine — and Windows,
across amd64, 386, arm64, armv7, armv6, armv5, and s390x.
Run the script installer as root (or with sudo). It installs a service,
sets up the x-ui management command, and enables the panel on boot.
The official script is the recommended path. During installation it generates a
random username, password, and access (web base) path, sets up the service,
and installs the x-ui management command.
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)Install a specific version by appending its tag:
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.4.0Install the rolling dev build (the latest per-commit pre-release from main
— not a stable release) by passing dev-latest:
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latestWhen it finishes, note the printed login details and run x-ui to open the
management menu, then
continue to First login.
The default Compose setup uses SQLite. Clone the repo (or copy its
docker-compose.yml and Dockerfile) and start it:
docker compose up -dTo run with the bundled PostgreSQL service, uncomment the two XUI_DB_*
lines in docker-compose.yml and start with the profile:
docker compose --profile postgres up -dPrefer the prebuilt image? It's published to the GitHub Container Registry. The
image bundles Fail2ban (for IP limits), which bans
with iptables and therefore needs NET_ADMIN (and NET_RAW for IPv6) —
otherwise bans are logged but never applied:
docker run -d \
--cap-add=NET_ADMIN \
--cap-add=NET_RAW \
-e XUI_ENABLE_FAIL2BAN=true \
-v $PWD/db/:/etc/x-ui/ \
-v $PWD/cert/:/root/cert/ \
--network=host \
--restart=unless-stopped \
--name 3x-ui \
ghcr.io/mhsanaei/3x-ui:latestThe db/ volume holds the SQLite database (/etc/x-ui/x-ui.db) and cert/
holds TLS certificates, so your data survives upgrades.
For advanced users, download a release archive for your architecture from the releases page, extract it, and run the binary as a systemd service. The install script automates exactly these steps, so it's preferred unless you have a specific reason to install by hand.
Build your install command
Tailor the command to your setup:
Install command builder
Build the exact install command for your setup. It is assembled in your browser.
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)Choose a database
You pick the storage backend at install time:
- SQLite (default) — a single file at
/etc/x-ui/x-ui.db. Zero setup. - PostgreSQL — for high client counts or multi-node setups. The installer can install it locally or use a DSN you provide.
See Database for details and SQLite→PostgreSQL migration.
Unattended / cloud-init
The installer also runs non-interactively for automation. Set
XUI_NONINTERACTIVE=1 (or run with no TTY) and it installs end-to-end with zero
prompts, generating random credentials and writing them to
/etc/x-ui/install-result.env:
XUI_NONINTERACTIVE=1 bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)The repo's deploy/
directory has ready-made cloud-init user-data for unattended installs on any
cloud (Hetzner, AWS, DigitalOcean, Vultr, GCP, Azure, Oracle).