View as Markdown

Installation

Quick install

curl -sSf https://getmeridian.org/install.sh | bash

This script:

  1. Installs uv if it is not present, with pipx or pip as fallbacks
  2. Installs meridian-vpn from PyPI
  3. Adds the tool directory to your shell PATH when needed
  4. Creates /usr/local/bin/meridian only when passwordless sudo is available

Manual install

With uv (recommended):

uv tool install meridian-vpn

With pipx:

pipx install meridian-vpn

Update

meridian update

Meridian checks PyPI now and then before interactive commands and prints a notice when a newer version exists. It never installs updates on its own. meridian update upgrades through whichever package manager installed it and confirms that the active meridian command reports the new version. Set MERIDIAN_DISABLE_UPDATE_CHECK=1 to turn off the background check in automation.

Updating the CLI changes nothing on your servers. If a server works, there is no rush; read the release notes, then run the same meridian deploy command (or meridian apply) when you are ready to apply the new version.

Upgrading from 3.x

Meridian 4.0 is not an in-place upgrade. It replaces the 3x-ui panel with Remnawave, and links from a 3.x server cannot carry over: every user needs a new link.

Your 3.x servers keep working. You have two choices:

  • Keep managing them with 3.x. Reinstall the 3.x CLI: 
    uv tool install 'meridian-vpn<4'
    (or pipx install 'meridian-vpn<4'). Meridian 3.17.3 and later stay on 3.x when you run meridian update, unless you pass --major.
  • Move to 4.0.
    1. Deploy a fresh server with 4.0: meridian deploy NEW_IP
    2. Give your users their new connection pages (meridian client add NAME for each person)
    3. Once everyone has switched, tear down the old server with meridian teardown OLD_IP — 4.0’s teardown also removes 3x-ui

Meridian 4.0 keeps its own state in ~/.config/meridian/ and never reads or changes 3.x state in ~/.meridian/, so both versions can live on one machine; fleet commands that find only 3.x state explain these options instead.

Requirements

  • Python 3.11+ (uv installs and manages it for you)
  • SSH key access to your server, as root or a user with passwordless sudo

Terminal QR codes are rendered by the bundled segno package; no system dependency is required.

Verify installation

meridian --version
On this page