First-Time Setup Guide

June 8, 2026 · View on GitHub

This guide walks you through setting up your development environment for contributing to the Hiero Python SDK.

Table of Contents

Repository Setup

Before you begin, make sure you have:

Step 1: Fork the Repository

Forking creates your own copy of the Hiero Python SDK that you can modify freely.

  1. Go to https://github.com/hiero-ledger/hiero-sdk-python
  2. Click the Fork button in the top-right corner
  3. Select your GitHub account as the destination

You now have your own fork at https://github.com/YOUR_USERNAME/hiero-sdk-python

Step 2: Clone Your Fork

Clone your fork to your local machine:

git clone https://github.com/YOUR_USERNAME/hiero-sdk-python.git
cd hiero-sdk-python

Replace YOUR_USERNAME with your actual GitHub username.

Step 3: Add Upstream Remote

Connect your local repository to the original Hiero SDK repository. This allows you to keep your fork synchronized with the latest changes.

git remote add upstream https://github.com/hiero-ledger/hiero-sdk-python.git

What this does:

  • origin = your fork (where you push your changes)
  • upstream = the original repository (where you pull updates from)

Step 4: Verify Your Remotes

Check that both remotes are configured correctly:

git remote -v

You should see:

origin    https://github.com/YOUR_USERNAME/hiero-sdk-python.git (fetch)
origin    https://github.com/YOUR_USERNAME/hiero-sdk-python.git (push)
upstream  https://github.com/hiero-ledger/hiero-sdk-python.git (fetch)
upstream  https://github.com/hiero-ledger/hiero-sdk-python.git (push)

Installation

Installing from PyPI

The latest release of this SDK is published to PyPI. You can install it with:

pip install --upgrade pip
pip install hiero-sdk-python

This will pull down a stable release along with the required dependencies.

Installing from Source

You can also clone the repo and install dependencies using uv: uv is an ultra-fast Python package and project manager. It replaces pip, pip-tools, pipx, poetry, pyenv, virtualenv, and more.

Install uv

On macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

On macOS (using Homebrew):

brew install uv

On Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Other installation methods: uv Installation Guide

Verify Installation

uv --version

Install Dependencies

uv automatically manages the correct Python version based on the .python-version file in the project, so you don't need to worry about version conflicts.

uv sync

What this does:

  • Downloads and installs the correct Python version (if needed)
  • Creates a virtual environment
  • Installs all project dependencies
  • Installs development tools (pytest, ruff, etc.)

Alternative: pip Editable Install

If you prefer using pip instead of uv, you can install in editable mode:

pip install --upgrade pip
pip install -e .

Note: This method requires you to have Python 3.10+ already installed on your system. Changes to your local code will be immediately reflected when you import the SDK.

Installing Optional Dependencies

Some SDK features (such as Ethereum-related functionality) rely on optional dependencies that are not installed by default.

These optional dependencies are required for:

  • Integration tests covering ETH-specific features
  • Running ETH-related example scripts

Optional dependencies are provided via extras.

Using pip

To install the SDK for local development with Ethereum support enabled:

pip install -e ".[eth]"

For most contributors, start with the standard development environment:

uv sync

If you are working on ETH functionality, running ETH-related tests, or executing ETH examples, install the ETH extra explicitly:

uv sync --dev --extra eth

Optional: To install all available extras (useful full-matrix testing):

uv sync --dev --all-extras

Pre-Commit Tool Setup

To maintain high code quality and security, this repository uses pre-commit hooks. These hooks automatically run checks (like Ruff for linting, Bandit for static security analysis and Gitleaks for security) every time you attempt to commit code.

Installation

Option 1: Using uv (Recommended)

uv is recommended because it manages pre-commit within your project’s locked environment, ensuring your local changes matches the CI exactly.

  1. Install the git hooks:
uv run pre-commit install
  1. Verify your setup (Optional):
uv run pre-commit run --all-files

Option 2: Using pip

If you are using a standard virtual environment:

  1. Install the package:
  pip install pre-commit
  1. Install the git hooks:
pre-commit install

Once installed, git commit will automatically trigger the checks.

  • If they pass: Your commit is created normally.
  • If they fail: Some hooks may auto-fix files (e.g., Ruff formatting). Others (e.g., Bandit) only report findings that you must fix manually, then git add and commit again.

Manual Execution

To run the hooks manually at any time:

# Run against only changed files
uv run pre-commit run

# Run against every file in the repository
uv run pre-commit run --all-files

Generate Protocol Buffers

The SDK uses protocol buffers to communicate with the Hedera network. Generate the Python code from the protobuf definitions:

uv run python generate_proto.py

Environment Setup

Create a .env file in the project root for your Hedera testnet credentials:

cp .env.example .env

Edit the .env file with your credentials:

OPERATOR_ID=0.0.YOUR_ACCOUNT_ID
OPERATOR_KEY=your_private_key_here
NETWORK=testnet

Don't have a testnet account? Get free testnet credentials at Hedera Portal

Optional environment variables:

ADMIN_KEY=...
SUPPLY_KEY=...
FREEZE_KEY=...
RECIPIENT_ID=...
TOKEN_ID=...
TOPIC_ID=...
VERIFY_CERTS=true  # Enable certificate verification for TLS (default: true)

These are only needed if you're customizing example scripts.

Note on TLS: The SDK uses TLS by default for hosted networks (testnet, mainnet, previewnet). For local networks (solo, localhost), TLS is disabled by default.

Verify Your Setup

Run the unit test suite to ensure your local setup is working:

uv run pytest tests/unit

You should see unit tests passing. Integration tests are expected to fail locally without the required network/test environment.

If you encounter errors, check that:

  • All dependencies installed correctly (uv sync)
  • Protocol buffers were generated (uv run python generate_proto.py)
  • Your .env file has valid credentials

Troubleshooting

"uv: command not found"

Make sure uv is in your PATH. After installation, you may need to restart your terminal or run:

source ~/.bashrc  # or ~/.zshrc on macOS

"Module not found" errors

If using uv:

uv sync
uv run python generate_proto.py

If using pip:

pip install -e .
python generate_proto.py

Tests fail with network errors

Check your .env file:

  • Is OPERATOR_ID correct?
  • Is OPERATOR_KEY correct?
  • Is NETWORK set to testnet?

Test your credentials at Hedera Portal

Need Help?