Installation

Install Hummingbot using Docker or from source for custom development

Hummingbot can be installed in two ways: using Docker for quick deployment, or from source for custom connector/strategy development.

Docker Installation (Recommended)

The easiest way to get started with Hummingbot is using Docker. This method works on Linux, macOS, and Windows.

1. Install Docker Compose

   First, install Docker Compose on your system:

   Linux

   # Install Docker Engine and Docker Compose
   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh
   sudo apt-get install docker-compose-plugin
   

   For detailed Docker installation instructions, visit the official Docker Compose documentation.
2. Clone the Hummingbot Repository

   Clone the repository and navigate to the directory:

   git clone https://github.com/hummingbot/hummingbot.git
   cd hummingbot
   
3. Run Setup

   Execute the setup command to configure your environment:

   make setup
   

   During setup, you’ll be prompted:

   Include Gateway? [y/N]
   

   Should I include Gateway?

   Answer y if you plan to:

   • Trade on DEXs (Uniswap, SushiSwap, Raydium, etc.)
   • Use AMM or CLMM strategies
   • Connect to DeFi protocols

   Answer N if you only plan to:

   • Trade on centralized exchanges (Binance, Coinbase, etc.)
   • Use CLOB strategies
4. Deploy Hummingbot

   Start the Hummingbot container:

   make deploy
   

   This will build and start the Docker containers in the background.

5. Attach to the Running Instance

   Connect to the Hummingbot CLI:

   docker attach hummingbot
   

   You should see the Hummingbot welcome screen:

   ██╗  ██╗██╗   ██╗███╗   ███╗███╗   ███╗██╗███╗   ██╗ ██████╗ ██████╗  ██████╗ ████████╗
   ██║  ██║██║   ██║████╗ ████║████╗ ████║██║████╗  ██║██╔════╝ ██╔══██╗██╔═══██╗╚══██╔══╝
   ███████║██║   ██║██╔████╔██║██╔████╔██║██║██╔██╗ ██║██║  ███╗██████╔╝██║   ██║   ██║
   ██╔══██║██║   ██║██║╚██╔╝██║██║╚██╔╝██║██║██║╚██╗██║██║   ██║██╔══██╗██║   ██║   ██║
   ██║  ██║╚██████╔╝██║ ╚═╝ ██║██║ ╚═╝ ██║██║██║ ╚████║╚██████╔╝██████╔╝╚██████╔╝   ██║
   ╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝ ╚═════╝ ╚═════╝  ╚═════╝    ╚═╝
   

To detach from the container without stopping it, press Ctrl+P followed by Ctrl+Q. To reattach later, run docker attach hummingbot.

Gateway Configuration

If you installed Gateway, you’ll need to configure it:

Development vs Production Mode

By default, Gateway starts in development mode with unencrypted HTTP endpoints. For production use:

1. Set the environment variable: DEV=false
2. Generate SSL certificates: gateway generate-certs (run inside Hummingbot)
3. Restart Gateway

See the Gateway documentation for details.

Source Installation

Install from source if you plan to:

• Develop custom connectors or strategies
• Modify core Hummingbot code
• Debug issues or contribute to the project

Source installation requires more technical expertise and maintenance compared to Docker. For most users, Docker is recommended.

1. Prerequisites

   Ensure you have the following installed:

   • Python 3.10+ with development headers
   • Anaconda or Miniconda (3.7+)
   • build-essential (Linux) or Xcode Command Line Tools (macOS)
   • git

   Linux

   # Install Anaconda
   wget https://repo.anaconda.com/archive/Anaconda3-latest-Linux-x86_64.sh
   bash Anaconda3-latest-Linux-x86_64.sh
   
   # Install build tools
   sudo apt-get update
   sudo apt-get install -y build-essential
   
2. Clone Repository

   git clone https://github.com/hummingbot/hummingbot.git
   cd hummingbot
   
3. Run Installation Script

   The installation script will create a conda environment and install dependencies:

   ./install
   

   For dYdX support (requires different dependencies):

   ./install --dydx
   

   This script will:

   • Create a conda environment named hummingbot
   • Install Python dependencies from setup/environment.yml
   • Install additional pip packages from setup/pip_packages.txt
   • Set up pre-commit hooks
   • On macOS, install the appnope package
4. Activate the Environment

   conda activate hummingbot
   
5. Compile Cython Extensions

   Hummingbot uses Cython for performance-critical components:

   ./compile
   

   You’ll need to recompile after making changes to .pyx files. The ./compile script handles this automatically.
6. Start Hummingbot

   ./start
   

   Or run directly:

   python bin/hummingbot_quickstart.py
   

Development Setup

If you’re developing custom code, you may want to install in editable mode:

# After activating the conda environment
conda develop .
python -m pip install -e .

This allows you to modify Python files without reinstalling the package.

Verify Installation

Once Hummingbot is running, verify your installation:

1. Check Version

   In the Hummingbot CLI, run:

   >>> version
   

   You should see output like:

   Version: 2.13.0
   
2. List Available Exchanges

   >>> connect
   

   This will show all available exchange connectors. The list should include major exchanges like binance, coinbase_advanced_trade, okx, etc.

3. Check Gateway (if installed)

   >>> gateway status
   

   If Gateway is running, you should see connection information.

Troubleshooting

Docker: Permission denied

If you get permission errors when running Docker commands:

# Add your user to the docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

Then log out and back in for changes to take effect.

Source: Compilation errors

If you encounter compilation errors:

1. Ensure you have the latest build tools:

   # Linux
   sudo apt-get update && sudo apt-get upgrade
   sudo apt-get install -y build-essential
   
   # macOS
   xcode-select --install
   

2. Clean and rebuild:

   ./clean
   ./compile
   

Conda environment issues

If the conda environment fails to create or activate:

# Remove existing environment
conda env remove -n hummingbot

# Recreate from environment file
conda env create -f setup/environment.yml

Missing TA-Lib

TA-Lib requires system libraries:

# Linux
wget http://prdownloads.sourceforge.net/ta-lib/ta-lib-0.4.0-src.tar.gz
tar -xzf ta-lib-0.4.0-src.tar.gz
cd ta-lib/
./configure --prefix=/usr
make
sudo make install

# macOS
brew install ta-lib

Next Steps

Quickstart Guide

Run your first trading bot

Connect Exchange

Set up API keys for your exchange

Choose a Strategy

Explore built-in strategies

Configure Gateway

Set up DEX trading (if installed)

For comprehensive troubleshooting, visit the Hummingbot documentation or ask in the Discord community.