How to upgrade Hyperledger Fabric components

Upgrading Hyperledger Fabric components replaces peer, orderer, Fabric CA, CouchDB, and client binaries while keeping existing ledger and MSP material intact. Network administrators perform this work before enabling newer channel capabilities or rolling out version-specific features across a channel.

Fabric treats a component upgrade as a binary or container replacement, not as a ledger migration. Ordering nodes should move first, peers follow in rolling order, and channel capability updates stay separate until every required node has the target binaries.

The sample flow uses a Docker CLI deployment with environment files and mounted ledger or MSP directories. Replace the container names, mounted paths, image tags, CA database backup command, and chaincode smoke test with values from the network being upgraded.

Related: Run the Hyperledger Fabric test network
Related: How to upgrade Hyperledger Fabric chaincode
Related: How to enable CouchDB for Hyperledger Fabric

Steps to upgrade Hyperledger Fabric components with Docker CLI:

  1. Set the target image tags and backup path for the maintenance window. 
    $ export FABRIC_IMAGE_TAG=3.1.5
$ export FABRIC_CA_IMAGE_TAG=1.5.21
$ export COUCHDB_IMAGE_TAG=3.4.2
$ export LEDGERS_BACKUP=/var/backups/fabric-components

    Use the Fabric, Fabric CA, and CouchDB versions approved for the network. Do not update channel capabilities until all required peers, orderers, and client tools are already on compatible binaries.

  2. Create the backup directory on the host. 
    $ mkdir -p "$LEDGERS_BACKUP"
  3. Check the current orderer version. 
    $ docker exec orderer.example.com orderer version
orderer:
 Version: v2.5.16
 Commit SHA: f871cf9
 Go version: go1.26.4
 OS/Arch: linux/amd64
  4. Check the current peer version. 
    $ docker exec peer0.org1.example.com peer version
peer:
 Version: v2.5.16
 Commit SHA: f871cf9
 Go version: go1.26.4
 OS/Arch: linux/amd64
 Chaincode:
  Base Docker Label: org.hyperledger.fabric
  Docker Namespace: hyperledger
  5. Check the current Fabric CA server version. 
    $ docker exec ca.org1.example.com fabric-ca-server version
fabric-ca-server:
 Version: v1.5.17
 Go version: go1.25.7
 OS/Arch: linux/amd64
  6. Stop one orderer container. 
    $ docker stop orderer.example.com
orderer.example.com

    Upgrade orderers one node at a time. Stopping enough orderers to lose quorum interrupts ordering service availability for every channel that depends on the ordering cluster.

  7. Back up the stopped orderer ledger directory. 
    $ docker cp orderer.example.com:/var/hyperledger/production/orderer "$LEDGERS_BACKUP/orderer.example.com"

    If the orderer already stores ledger data on a host volume, also take the normal host-volume or storage-layer backup before replacing the container.

  8. Remove the old orderer container. 
    $ docker rm orderer.example.com
orderer.example.com
  9. Start the orderer with the target Fabric image. 
    $ docker run --detach \
  --name orderer.example.com \
  --env-file ./env-orderer.example.com.list \
  --volume /opt/fabric/orderer.example.com/msp:/etc/hyperledger/fabric/msp \
  --volume /opt/fabric/orderer.example.com/tls:/etc/hyperledger/fabric/tls \
  --volume /opt/fabric/orderer.example.com/production:/var/hyperledger/production/orderer \
  hyperledger/fabric-orderer:"$FABRIC_IMAGE_TAG" orderer
6d10a8e8f086d3b7190d7a1cfd8a5e5d8935efb0e8bb0f404c1d7c71e8d47c83

    Use the same environment file, MSP, TLS material, listen ports, and ledger volume that the previous orderer used unless the upgrade plan intentionally changes them.

  10. Verify the upgraded orderer version. 
    $ docker exec orderer.example.com orderer version
orderer:
 Version: v3.1.5
 Commit SHA: 86c1172
 Go version: go1.26.4
 OS/Arch: linux/amd64
  11. Stop one peer container after its orderer dependencies are upgraded. 
    $ docker stop peer0.org1.example.com
peer0.org1.example.com
  12. Back up the stopped peer ledger directory. 
    $ docker cp peer0.org1.example.com:/var/hyperledger/production "$LEDGERS_BACKUP/peer0.org1.example.com"

    A peer with CouchDB also needs the matching CouchDB data backup before the peer returns to service.

  13. List peer-owned chaincode containers before removing the peer. 
    $ docker container ls --all --filter "name=dev-peer0.org1.example.com"
CONTAINER ID   IMAGE                                    COMMAND                  CREATED       STATUS       NAMES
a9dc7b1c0d2e   dev-peer0.org1.example.com-basic_1.0     "chaincode -peer.add…"   2 months ago  Exited (0)   dev-peer0.org1.example.com-basic_1.0-a9dc7b1c
  14. Remove the peer-owned chaincode container that must be rebuilt on the upgraded peer runtime. 
    $ docker rm --force dev-peer0.org1.example.com-basic_1.0-a9dc7b1c
dev-peer0.org1.example.com-basic_1.0-a9dc7b1c

    Remove only chaincode containers that belong to the peer being replaced. Other peers continue endorsing while this peer is offline.

  15. Remove the old peer container. 
    $ docker rm peer0.org1.example.com
peer0.org1.example.com
  16. Start the peer with the target Fabric image. 
    $ docker run --detach \
  --name peer0.org1.example.com \
  --env-file ./env-peer0.org1.example.com.list \
  --volume /opt/fabric/peer0.org1.example.com/msp:/etc/hyperledger/fabric/msp \
  --volume /opt/fabric/peer0.org1.example.com/tls:/etc/hyperledger/fabric/tls \
  --volume /opt/fabric/peer0.org1.example.com/production:/var/hyperledger/production \
  hyperledger/fabric-peer:"$FABRIC_IMAGE_TAG" peer node start
25d7d61c3f67cc02379d1ee167b5a2ab6fa66d0c5dc6ee9f1bd9a3d7df5a9ad0

    Repeat the peer stop, backup, chaincode-container cleanup, remove, start, and version check for each peer in the organization before moving to the next organization.

  17. Verify the upgraded peer version. 
    $ docker exec peer0.org1.example.com peer version
peer:
 Version: v3.1.5
 Commit SHA: 86c1172
 Go version: go1.26.4
 OS/Arch: linux/amd64
 Chaincode:
  Base Docker Label: org.hyperledger.fabric
  Docker Namespace: hyperledger
  18. Stop the CouchDB container paired with the peer. 
    $ docker stop couchdb0.org1.example.com
couchdb0.org1.example.com
  19. Back up the CouchDB data directory. 
    $ docker cp couchdb0.org1.example.com:/opt/couchdb/data "$LEDGERS_BACKUP/couchdb0.org1.example.com"
  20. Remove the old CouchDB container. 
    $ docker rm couchdb0.org1.example.com
couchdb0.org1.example.com
  21. Start CouchDB with the approved target image. 
    $ docker run --detach \
  --name couchdb0.org1.example.com \
  --env-file ./env-couchdb0.org1.example.com.list \
  --volume /opt/fabric/couchdb0.org1.example.com/data:/opt/couchdb/data \
  couchdb:"$COUCHDB_IMAGE_TAG"
1dbd0f9180ff4a4a7f1dc33d24de1e177d6d14c7c3f7dd5ef5c8759a5fbb0fc1

    Keep the peer offline while its CouchDB data store is being replaced. A peer and its state database must return as a matched pair.

  22. Check that CouchDB answers on the upgraded container. 
    $ curl -u "$COUCHDB_USER:$COUCHDB_PASSWORD" http://couchdb0.org1.example.com:5984/
{"couchdb":"Welcome","version":"3.4.2","git_sha":"690552d","uuid":"0d37f8c7f977f02e"}
  23. Stop the Fabric CA server container. 
    $ docker stop ca.org1.example.com
ca.org1.example.com
  24. Back up the Fabric CA server home directory. 
    $ docker cp ca.org1.example.com:/etc/hyperledger/fabric-ca-server "$LEDGERS_BACKUP/ca.org1.example.com"

    Use the deployment's database backup tool when the CA server stores identities in PostgreSQL, MySQL, or another external database instead of the default local database file.

  25. Remove the old Fabric CA server container. 
    $ docker rm ca.org1.example.com
ca.org1.example.com
  26. Start the Fabric CA server with the target CA image. 
    $ docker run --detach \
  --name ca.org1.example.com \
  --env-file ./env-ca.org1.example.com.list \
  --volume /opt/fabric/ca.org1.example.com:/etc/hyperledger/fabric-ca-server \
  hyperledger/fabric-ca:"$FABRIC_CA_IMAGE_TAG" fabric-ca-server start
c280b36f23030d89732709514c7a5a7ed0a0c1a76f0f79596b125dd62729a3e9
  27. Verify the upgraded Fabric CA server version. 
    $ docker exec ca.org1.example.com fabric-ca-server version
fabric-ca-server:
 Version: v1.5.21
 Go version: go1.26.4
 OS/Arch: linux/amd64

    Renew or reenroll identities only when the upgrade plan also changes certificate material or when certificates are near expiry.
    Related: How to renew a Hyperledger Fabric certificate

  28. Upgrade Fabric Gateway client dependencies after the nodes accept traffic on the target binaries. 
    $ npm install @hyperledger/fabric-gateway@latest
changed 3 packages, and audited 104 packages in 2s
found 0 vulnerabilities

    Use the package manager for the application language, such as npm, Go modules, Maven, or pip. Keep the client SDK change in a separate application release if the node upgrade needs a fast rollback path.

  29. Run a chaincode query through an upgraded peer. 
    $ peer chaincode query -C mychannel -n basic -c '{"Args":["ReadAsset","asset1"]}'
{"ID":"asset1","color":"blue","size":5,"owner":"Tomoko","appraisedValue":300}

    The query confirms that the upgraded peer, orderer path, state database, and client binary can still read committed ledger state. Use a write transaction as the final smoke test when the maintenance plan allows a harmless test update.
    Related: How to query Hyperledger Fabric chaincode