How to install Hyperledger Fabric on macOS

Installing Hyperledger Fabric on macOS prepares a local fabric-samples workspace with Fabric command-line binaries, default configuration files, and Docker images for the sample network. The setup gives developers and platform operators a workstation baseline before running Fabric tutorials, testing chaincode, or inspecting Fabric commands locally.

The official install-fabric.sh script clones fabric-samples into the directory where it runs, downloads platform-specific binaries into fabric-samples/bin, places default configuration files under fabric-samples/config, and pulls the Fabric container images through Docker Desktop. The script selects the matching darwin-arm64 or darwin-amd64 binary package from the Mac architecture.

Docker Desktop must be installed, open, and connected to its engine before the image pull step. Keep the Fabric workspace in a project directory you plan to reuse, and run the test network as a separate follow-on check after the install commands show the binaries and images are present.

1. Open Terminal.
2. Install Homebrew if brew is not already available.

   $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   Homebrew installs or prompts for the Xcode Command Line Tools when they are missing.

3. Confirm Homebrew is available.

   $ brew --version
   Homebrew 6.0.2

4. Install the Fabric prerequisite tools.

   $ brew install git curl jq

   Git clones fabric-samples, curl downloads the installer and binary archives, and jq is used by Fabric sample-network scripts.

5. Install Docker Desktop with Homebrew Cask.

   $ brew install --cask --appdir="/Applications" docker

6. Open Docker Desktop.

   $ open /Applications/Docker.app

   Finish the first-run prompts and wait until Docker Desktop shows that the engine is running.

7. Confirm the Docker engine is reachable.

   $ docker --version
   Docker version 29.5.3, build d1c06ef6b4

8. Confirm the Docker Compose plugin is available.

   $ docker compose version
   Docker Compose version v5.1.4

9. Create a Fabric workspace.

   $ mkdir -p "$HOME/fabric"

10. Enter the Fabric workspace.

    $ cd "$HOME/fabric"

11. Download the official Fabric installer script.

    $ curl -fsSLO https://raw.githubusercontent.com/hyperledger/fabric/main/scripts/install-fabric.sh

12. Make the installer executable.

    $ chmod +x install-fabric.sh

13. 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.

14. 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. If Docker reports a credential-helper or engine error, keep Docker Desktop open, confirm docker --version works, and rerun the same installer command.

15. Enter the samples directory created by the installer.

    $ cd fabric-samples

16. Add the Fabric binaries and configuration directory to the current terminal session.

    $ export PATH="$PWD/bin:$PATH"
    $ export FABRIC_CFG_PATH="$PWD/config"

    This changes only the current terminal session. Add equivalent exports to a shell profile only when you want Fabric commands available in every new terminal.

17. Verify the Fabric peer binary.

    $ peer version
    peer:
     Version: v2.5.16
     Commit SHA: f871cf9
     Go version: go1.26.4
     OS/Arch: darwin/arm64
     Chaincode:
      Base Docker Label: org.hyperledger.fabric
      Docker Namespace: hyperledger

    OS/Arch shows darwin/amd64 on Intel Macs.

18. Verify the Fabric CA client binary.

    $ fabric-ca-client version
    fabric-ca-client:
     Version: v1.5.17
     Go version: go1.25.7
     OS/Arch: darwin/arm64

19. 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

    After these checks pass, use fabric-samples/test-network/network.sh from the same workspace to start a local sample network.
    Related: Run the Hyperledger Fabric test network