Skip to main content
Install the Uncloud command-line utility to manage your machines and deploy apps using uc commands. You will run uc locally on your development machine, so choose the appropriate installation method for your operating system.
The Uncloud CLI is a local tool. It doesn’t need to be installed on your servers. The uc machine init command will automatically install the necessary components (uncloudd daemon) on your remote machines.

​
macOS

If you have Homebrew package manager installed, this is the recommended installation method: 
brew install psviderski/tap/uncloud
This installs both the uncloud binary and creates a convenient uc shortcut. To upgrade to the latest version: 
brew upgrade uncloud

​
Install script

For a quick automated installation without Homebrew: 
curl -fsS https://get.uncloud.run/install.sh | sh
The script will:
  • Detect your macOS architecture (Apple Silicon or Intel)
  • Download the appropriate latest binary from GitHub releases
  • Install it to /usr/local/bin/uncloud using sudo (you may need to enter your password)
  • Create a shortcut uc in /usr/local/bin for convenience
Don’t like curl | sh? You can download and review the install script first:
curl -fsSO https://get.uncloud.run/install.sh
cat install.sh
sh install.sh

​
Manual download

Download the binary directly from GitHub releases: 
curl -L https://github.com/psviderski/uncloud/releases/latest/download/uncloud_macos_arm64.tar.gz | tar xz
sudo mv uncloud /usr/local/bin/
sudo ln -s /usr/local/bin/uncloud /usr/local/bin/uc

​
Linux

The easiest way to install on Linux: 
curl -fsS https://get.uncloud.run/install.sh | sh
The script will:
  • Auto-detect your Linux architecture (AMD64 or ARM64)
  • Download the latest binary
  • Install to /usr/local/bin/uncloud
  • Create the uc shortcut
  • Verify the installation with checksum validation

​
Homebrew

If you have Homebrew installed on Linux: 
brew install psviderski/tap/uncloud

​
Manual download

curl -L https://github.com/psviderski/uncloud/releases/latest/download/uncloud_linux_amd64.tar.gz | tar xz
sudo mv uncloud /usr/local/bin/
sudo ln -s /usr/local/bin/uncloud /usr/local/bin/uc

​
Debian/Ubuntu package

On Debian-based systems, you can install from an unofficial repository maintained by @dariogriffo: 
curl -sS https://debian.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/trusted.gpg.d/debian.griffo.io.gpg
echo "deb https://debian.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/debian.griffo.io.list
sudo apt update
sudo apt install -y uncloud
Alternatively, download .deb packages directly from the repository releases.

​
Windows

Windows is not natively supported yet, but you can install and run uc in a WSL (Windows Subsystem for Linux) terminal.
1

Enable WSL

If you haven’t already, install WSL:
wsl --install
2

Install in WSL

Open your WSL terminal (Ubuntu) and follow the Linux installation instructions:
curl -fsS https://get.uncloud.run/install.sh | sh

​
Install from source

If you have Go 1.21 or later installed, you can build from source: 
go install github.com/psviderski/uncloud/cmd/uncloud@latest
The binary will be installed to $GOPATH/bin/uncloud. Make sure $GOPATH/bin is in your PATH. To create the uc shortcut: 
ln -s $(which uncloud) $(dirname $(which uncloud))/uc
Building from source installs the latest development version, which may be unstable. Use a released version for normal use.

​
Custom installation directory

By default, the install script places binaries in /usr/local/bin. You can customize this: 
INSTALL_DIR=$HOME/.local/bin curl -fsS https://get.uncloud.run/install.sh | sh
Make sure your custom directory is in your system’s PATH.

​
Verify installation

After installation, verify that the uc command works: 
uc --version
You should see output like: 
uncloud version v0.x.x

​
Update Uncloud

The update process depends on your installation method: Homebrew: 
brew upgrade uncloud
Install script or manual download: Re-run the installation command to download and install the latest version: 
curl -fsS https://get.uncloud.run/install.sh | sh
From source: 
go install github.com/psviderski/uncloud/cmd/uncloud@latest

​
Uninstall

To remove the Uncloud CLI from your local machine: Homebrew: 
brew uninstall uncloud
Manual installation: 
sudo rm /usr/local/bin/uncloud /usr/local/bin/uc
Remove cluster configuration (optional): This removes saved cluster credentials and context: 
rm -rf ~/.config/uncloud
Uninstalling the CLI from your local machine doesn’t affect Uncloud components running on your servers. To remove Uncloud from a machine, SSH into it and run uncloud-uninstall.

​
Troubleshooting

​
Command not found

If you get command not found: uc after installation:
  1. Check that /usr/local/bin is in your PATH: 
    echo $PATH
  2. If not, add it to your shell profile (~/.bashrc, ~/.zshrc, etc.): 
    export PATH="/usr/local/bin:$PATH"
  3. Reload your shell: 
    source ~/.bashrc  # or ~/.zshrc

​
Permission denied

If you get permission errors when running the install script, make sure you’re using sudo or the script is using sudo internally. The script needs to write to /usr/local/bin.

​
Checksum verification failed

If checksum verification fails during installation:
  1. Try downloading again (might be a network issue)
  2. Check the GitHub releases page for known issues
  3. Manually download and verify the checksums

​
Next steps

Quickstart

Deploy your first app in minutes

CLI reference

Explore all available commands

Build docs developers (and LLMs) love

Get started for freeTalk to us