Installation

This guide demonstrates the installation steps of ORAS CLI v1.2.1 on different platforms.

Homebrew

Install oras using Homebrew:

brew install oras

Snap

Install oras using Snap:

snap install oras --classic

Release artifacts

Install ORAS from the latest release artifacts:

Linux

If you want to install ORAS on an AMD64-based Linux machine, run the following command:

VERSION="1.2.1"
curl -LO "https://github.com/oras-project/oras/releases/download/v${VERSION}/oras_${VERSION}_linux_amd64.tar.gz"
mkdir -p oras-install/
tar -zxf oras_${VERSION}_*.tar.gz -C oras-install/
sudo mv oras-install/oras /usr/local/bin/
rm -rf oras_${VERSION}_*.tar.gz oras-install/

note

If you want to install ORAS on an ARM64-based Linux machine, you can download it from https://github.com/oras-project/oras/releases/download/v1.2.1/oras_1.2.1_linux_arm64.tar.gz.

macOS

If you want to install ORAS on a Mac computer with Apple silicon, run the following command:

VERSION="1.2.1"
curl -LO "https://github.com/oras-project/oras/releases/download/v${VERSION}/oras_${VERSION}_darwin_arm64.tar.gz"
mkdir -p oras-install/
tar -zxf oras_${VERSION}_*.tar.gz -C oras-install/
sudo mv oras-install/oras /usr/local/bin/
rm -rf oras_${VERSION}_*.tar.gz oras-install/

note

If you want to install ORAS on an Intel-based Mac, you can download it from https://github.com/oras-project/oras/releases/download/v1.2.1/oras_1.2.1_darwin_amd64.tar.gz. ORAS on Homebrew is not maintained by the ORAS community, so it may not be the latest version.

Windows

• You can install ORAS CLI on Windows using WinGet (Windows Package Manager):

winget install oras --version 1.2.1

• Alternatively, you can install ORAS CLI using .exe installer. Add %USERPROFILE%\bin\ to your PATH environment variable so that oras.exe can be found.

set VERSION="1.2.1"
curl.exe -sLO  "https://github.com/oras-project/oras/releases/download/v%VERSION%/oras_%VERSION%_windows_amd64.zip"
tar.exe -xvzf oras_%VERSION%_windows_amd64.zip
mkdir -p %USERPROFILE%\bin\
copy oras.exe %USERPROFILE%\bin\
set PATH=%USERPROFILE%\bin\;%PATH%

Docker Image

A public Docker image containing the CLI is available on GitHub Container Registry:

docker run -it --rm -v $(pwd):/workspace ghcr.io/oras-project/oras:v1.2.1 help

note

The default WORKDIR in the image is /workspace.

You can use the Docker image locally instead of installing a binary. For example create an alias:

alias doras='docker run -it --rm -v $(pwd):/workspace ghcr.io/oras-project/oras:v1.2.1'

Run ORAS commands:

doras pull ghcr.io/$GH_USER/oras:darwin-amd64 --username $GH_USER --password $GHCR_TOKEN -o ./download

GitHub Actions

Use the oras CLI of the default version in GitHub Actions workflow using setup-oras:

steps:
  - uses: oras-project/setup-oras@v1
  - run: oras version

Reference the Advanced Usage to learn more.

Runner machine of Azure DevOps and GitHub Actions

ORAS CLI is also a built-in tool in some VM images for GitHub-hosted runners used for GitHub Actions, as well as for Microsoft-hosted agents used for Azure Pipelines. You can use ORAS CLI on these two operating system out of the box:

• Ubuntu 20.04
• Ubuntu 22.04

note

ORAS on runner images is not maintained by the ORAS community, so it may not be the latest version.

Nix

Nix is a tool that takes a unique approach to package management and system configuration.

The Nix Packages collection (Nixpkgs) is a set of over 80 000 packages for the Nix package manager.

oras also has a Nix package available in the Nixpkgs repository.

info

You can install nix CLI from here.

You can install oras using the following command:

nix-env -iA nixpkgs.oras

note

ORAS on Nix is not maintained by the ORAS community, so it may not be the latest version.

Verify

$ oras version
Version:        1.2.1
Go version:     go1.23.4
Git commit:     a0228556766b6276010d8feb937af512e8a50808
Git tree state: clean

You can check out our how-to guide if you would like to verify ORAS CLI Binaries.