Install

Perform the following steps to install yb-voyager using apt for Ubuntu:

1. Install the Yugabyte apt repository on your machine using the following command:

   wget https://software.yugabyte.com/repos/reporpms/yb-apt-repo_1.0.0_all.deb
   sudo apt-get install ./yb-apt-repo_1.0.0_all.deb
   

   This repository contains the yb-voyager Debian package and the dependencies required to run yb-voyager.

2. Install the postgresql-common repository to fetch PostgreSQL 16 using the following commands:

   sudo apt install -y postgresql-common
   sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
   

3. Clean the apt-get cache and package lists using the following commands:

   sudo apt-get clean
   sudo apt-get update
   

4. Install yb-voyager and its dependencies using the following command:

   sudo apt-get install yb-voyager
   

   Note: If you see a failure in the install step similar to the following:

   Depends: ora2pg (= 23.2-yb.2) but 24.3-1.pgdg22.04+1 is to be installed
   

   Try installing ora2pg using the following command:

   sudo apt-get install ora2pg=23.2-yb.2
   

   Then try installing yb-voyager using the following command:

   sudo apt-get install yb-voyager
   

5. Check that yb-voyager is installed using the following command:

   yb-voyager version
   

Dependencies

YugabyteDB Voyager relies on the following dependencies on supported Ubuntu systems, which are automatically installed or resolved when you install Voyager using the official package.

Upgrade yb-voyager

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

Upgrade yb-voyager using the following command:

sudo apt-get upgrade yb-voyager

Perform the following steps to install yb-voyager using brew for macOS:

1. Tap the yugabyte Homebrew repository using the following command:

   brew tap yugabyte/tap
   

   The repository contains the formula to build and install yb-voyager on your macOS device.

   Note that the tap yugabyte/yugabytedb has been updated to yugabyte/tap. If you have previously installed yb-voyager using the tap yugabyte/yugabytedb, untap the entry using brew untap yugabyte/yugabytedb, and then tap using the preceding command.

2. Install PostgreSQL 17 (required for pg_dump and pg_restore) using Homebrew:

   brew install postgresql@17
   

   After installing PostgreSQL 17, Homebrew displays instructions on how to add the PostgreSQL 17 binaries to your shell's PATH. These steps vary depending on your system's Homebrew installation path (for example: /opt/homebrew or /usr/local) and the shell you are using.

   1. Update your PATH by following the exact instructions shown by Homebrew. Following is an example of what Homebrew may display:

      If you need to have postgresql@17 first in your PATH, run:
      echo 'export PATH="/opt/homebrew/opt/postgresql@17/bin:$PATH"' >> ~/.zshrc
      For compilers to find postgresql@17 you may need to set:
      export LDFLAGS="-L/opt/homebrew/opt/postgresql@17/lib"
      export CPPFLAGS="-I/opt/homebrew/opt/postgresql@17/include"
      

   2. After the update, restart your terminal and verify that both report to PostgreSQL 17:

      pg_dump --version
      pg_restore --version
      

3. Install yb-voyager and its dependencies using the following command:

   brew install yb-voyager
   

   To install a specific version of yb-voyager, use the following command:

   brew install yb-voyager@<VERSION>
   

4. Check that yb-voyager is installed using the following command:

   yb-voyager version
   

Dependencies

When installing YugabyteDB Voyager using Homebrew, the following dependencies are installed automatically as part of the formula.

• yugabyte/tap/debezium@2.5.2-\<voyager_version\>
• postgresql@17
• sqlite
• go@1.24 (build-time)

• Docker
• Yum
• Ubuntu

Prerequisites

Before installing yb-voyager in Docker, ensure that you have the following:

1. Docker runtime installed on your machine.
2. Docker is configured to run without sudo (recommended). Refer to Manage Docker as a non-root user in the Docker documentation.

Install

Perform the following steps to install yb-voyager:

1. Pull the docker image from YugabyteDB's docker hub (pull the version from docker.io) as follows:

   docker pull software.yugabyte.com/yugabytedb/yb-voyager
   

2. Run yb-voyager using one of the following methods:

   Method 1: Use the Wrapper script

   1. Download the script to run yb-voyager using the docker image from yb-voyager's GitHub repository, and move it to your machine's bin directory using the following commands:

      wget -O ./yb-voyager https://raw.githubusercontent.com/yugabyte/yb-voyager/main/docker/yb-voyager-docker && \
      chmod +x ./yb-voyager && \
      sudo mv yb-voyager /usr/local/bin/yb-voyager
      

   2. Verify the installation:

      yb-voyager version
      

   Limitations:

   • Configuration file is not supported.
   • When using import-data-file, the import data status and end-migration commands do not work.
   • Certain shorthand flags (like -e) are not propagated properly to the docker container.

   Method 2: Use the Container directly

   Run the container directly with volume mounts.

   1. Run the container with an interactive shell:

      docker run -it --rm \
        --network=host \
        -v /path/to/export-dir/on/host:/home/ubuntu/export-dir \
        yugabytedb/yb-voyager bash
      

   2. Once inside the container, run any yb-voyager command. For example, to verify the installation:

      yb-voyager version
      

      Mount directories

      Mount all directories that yb-voyager needs to access (export directory, configuration files, SSL certificates, and so on). On macOS, add --platform=linux/amd64 to the docker run command.

Perform the following steps to install yb-voyager using an installer script:

1. Clone the yb-voyager repository.

   git clone https://github.com/yugabyte/yb-voyager.git
   

2. Change the directory to yb-voyager/installer_scripts.

   cd yb-voyager/installer_scripts
   

3. Install yb-voyager using the following script:

   ./install-yb-voyager
   

   To install a specific version of yb-voyager on your machine, use the following command:

   ./install-yb-voyager --version <VERSION>
   

   It is safe to execute the script multiple times. If the script fails, check the /tmp/install-yb-voyager.log file.

4. The script generates a .yb-voyager.rc file in the home directory. Source the file to ensure that the environment variables are set using the following command:

   source ~/.yb-voyager.rc
   

5. Check that yb-voyager is installed using the following command:

   yb-voyager version