Installing Hyperledger Fabric on Ubuntu or Debian prepares a local fabric-samples workspace with Fabric command-line binaries, default configuration files, and Docker images for the sample network. Developers and platform operators use this Linux baseline before running Fabric tutorials, testing chaincode, or inspecting peer and certificate authority commands locally.
The official install-fabric.sh script clones fabric-samples into the directory where it runs, downloads Linux binaries into fabric-samples/bin, places default configuration files under fabric-samples/config, and pulls the Fabric container images through Docker. On current Ubuntu releases, the Compose v2 plugin is packaged as docker-compose-v2 and used through docker compose.
Keep the Fabric workspace in a project directory you plan to reuse. Docker group changes affect new login sessions, and the install is complete when peer, fabric-ca-client, and a Fabric peer container all report the expected Fabric versions.
Steps to install Hyperledger Fabric on Ubuntu or Debian:
- Open a terminal with sudo privileges.
- Refresh the APT package index.
$ sudo apt update
- Install the Fabric prerequisite packages.
$ sudo apt install --assume-yes ca-certificates curl git jq docker.io docker-compose-v2
Git clones fabric-samples, curl downloads the installer and binary archives, jq is used by Fabric sample scripts, and docker-compose-v2 provides the docker compose command. On an older Debian release where docker-compose-v2 is unavailable, install Docker Engine with the Compose plugin from Docker's repository before continuing.
- Start and enable the Docker service.
$ sudo systemctl enable --now docker
- Add your user to the Docker group.
$ sudo usermod --append --groups docker "$USER"
The docker group can control the Docker daemon. Add only trusted local users.
- Log out and back in so the Docker group membership applies.
- Confirm Docker can reach the daemon.
$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
- Confirm the Docker Compose plugin is available.
$ docker compose version Docker Compose version 2.40.3+ds1-0ubuntu1
- Create a Fabric workspace.
$ mkdir -p "$HOME/fabric"
- Enter the Fabric workspace.
$ cd "$HOME/fabric"
- Download the official Fabric installer script.
$ curl -fsSLO https://raw.githubusercontent.com/hyperledger/fabric/main/scripts/install-fabric.sh
- Make the installer executable.
$ chmod +x install-fabric.sh
- Review the installer options and version defaults.
$ ./install-fabric.sh -h Usage: ./install-fabric.sh [-f|--fabric-version <arg>] [-c|--ca-version <arg>] <comp-1> [<comp-2>] ... [<comp-n>] ... <comp> Component to install, one or more of docker | binary | samples | podman First letter of component also accepted; If none specified docker | binary | samples is assumed -f, --fabric-version: FabricVersion (default: '2.5.16') -c, --ca-version: Fabric CA Version (default: '1.5.17')The script help from the downloaded copy is the version source for that install run. Pin versions with --fabric-version and --ca-version only when matching a specific Fabric lab or release line.
- Install the samples, Fabric binaries, and Docker images.
$ ./install-fabric.sh docker binary samples Clone hyperledger/fabric-samples repo ===> Cloning hyperledger/fabric-samples repo ##### snipped ##### Pull Hyperledger Fabric binaries ===> Downloading version 2.5.16 platform specific fabric binaries ==> Done. ===> Downloading version 1.5.17 platform specific fabric-ca-client binary ==> Done. Pull Hyperledger Fabric docker images FABRIC_IMAGES: peer orderer ccenv baseos ===> Pulling fabric Images ##### snipped ##### ===> Pulling fabric ca Image ##### snipped ##### ===> List out hyperledger images
The Docker image pull can take several minutes. Rerun the same command after fixing any network, registry, or Docker daemon error.
- Enter the samples directory created by the installer.
$ cd fabric-samples
- Add the Fabric binaries to the current shell.
$ export PATH="$PWD/bin:$PATH"
- Set the Fabric configuration path for local commands.
$ export FABRIC_CFG_PATH="$PWD/config"
These exports change only the current terminal session. Add equivalent lines to a shell profile only when you want Fabric commands available in every new terminal.
- Verify the Fabric peer binary.
$ peer version peer: Version: v2.5.16 Commit SHA: f871cf9 Go version: go1.26.4 OS/Arch: linux/arm64 Chaincode: Base Docker Label: org.hyperledger.fabric Docker Namespace: hyperledger
OS/Arch shows linux/amd64 on x86_64 Ubuntu or Debian hosts.
- Verify the Fabric CA client binary.
$ fabric-ca-client version fabric-ca-client: Version: v1.5.17 Go version: go1.25.7 OS/Arch: linux/arm64
- Confirm the Fabric Docker images are tagged locally.
$ docker image ls --filter reference='hyperledger/fabric-*:2.5.16' --filter reference='hyperledger/fabric-ca:1.5.17' IMAGE ID DISK USAGE CONTENT SIZE EXTRA hyperledger/fabric-baseos:2.5.16 109b4a15b282 245MB 80.2MB hyperledger/fabric-ca:1.5.17 453a0a727e82 358MB 116MB hyperledger/fabric-ccenv:2.5.16 807493f095f6 972MB 248MB hyperledger/fabric-orderer:2.5.16 1d918fc7e1e0 167MB 46.8MB hyperledger/fabric-peer:2.5.16 58979b65744b 215MB 62MB
- Run the Fabric peer image as a smoke test.
$ docker run --rm hyperledger/fabric-peer:2.5.16 peer version peer: Version: v2.5.16 Commit SHA: f871cf9 Go version: go1.26.4 OS/Arch: linux/arm64 Chaincode: Base Docker Label: org.hyperledger.fabric Docker Namespace: hyperledger
After these checks pass, start the sample network from fabric-samples/test-network/network.sh in the same workspace.
Related: Run the Hyperledger Fabric test network
Mohd Shakir Zakaria is a cloud architect with deep roots in software development and open-source advocacy. Certified in AWS, Red Hat, VMware, ITIL, and Linux, he specializes in designing and managing robust cloud and on-premises infrastructures.
