Native Linux deployment#

Supports Debian, Ubuntu and Alpine. Startup installs system dependencies and configures services including nginx; use a dedicated environment. Install Node.js, npm, Python3 and pip3 first. The 2.24.0 npm panel package has been verified on Node.js 20 and 24; panel and script dependencies use pnpm 8.3.1. The standalone remote CLI requires Node.js 22.12 or newer. Default containers use Python 3.11; native deployments need a Python version compatible with user scripts.

Install and configure paths#

Install 2.24.0:

npm install -g @whyour/qinglong@2.24.0

After installation, configure the paths and start the panel:

export QL_DIR="$(npm root -g)/@whyour/qinglong"
export QL_DATA_DIR="$HOME/qinglong/data"
mkdir -p "$QL_DATA_DIR"
qinglong

QL_DIR is the installed panel directory. QL_DATA_DIR stores persistent data and must be an absolute path ending in /data. Use the same user and npm environment as installation; do not leave either path empty. Persist these variables in the actual panel user or service environment for subsequent starts.

Open http://localhost:5700, initialize the panel and create your first task.

@whyour/qinglong installs the panel; @whyour/qinglong-cli installs the remote client. Both provide ql; see the CLI guide for separate entrypoints.

Back up all data before upgrading and keep QL_DATA_DIR pointing to the existing data directory. For an isolated Python venv on a native installation, follow the native deployment guide. Follow the Docker guide to pull and recreate containers. If dependencies fail to load, reinstall the affected packages through Dependency Management and inspect the logs.