Install via Docker

We recommend installing Hummingbot using Docker if you want the simplest, easiest installation method and don't need to modify the Hummingbot codebase.

Prerequisites

Cloud or local machine

Component	Specification
Operating System	MacOS 10.12.6+ / Linux (Ubuntu 20.04+, Debian 10+) / Windows 10+
Memory	4 GB RAM per instance
Storage	5 GB HDD space per instance
CPU	at least 1 vCPU per instance / controller

Docker Compose

Hummingbot uses Docker Compose, a tool for defining and running multi-container Docker applications. Docker Desktop already includes Docker Compose along with Docker Engine and Docker CLI, which are Compose prerequisites.

For Windows users

To install Hummingbot on Windows, you need to have Docker Desktop installed, set up Windows Subsystem for Linux 2 (WSL2), and install a Linux distribution like Ubuntu. Make sure to run the commands listed below from within an Ubuntu terminal and not from the Windows Command Prompt or PowerShell.

Installation (Dashboard)

Starting with Hummingbot release 2.0, the new Deploy repo helps you launch Dashboard and Backend-API to make creating and launching bots easier.

git clone https://github.com/hummingbot/deploy.git
cd deploy
bash setup.sh

The setup script will pull the Docker images defined in repo's docker-compose.yml file and start them as new containers:

[+] Running 7/7
 ✔ Network deploy_emqx-bridge   Created
 ✔ Volume "deploy_emqx-data"    Created
 ✔ Volume "deploy_emqx-log"     Created
 ✔ Volume "deploy_emqx-etc"     Created
 ✔ Container dashboard          Started 
 ✔ Container backend-api        Started 
 ✔ Container hummingbot-broker  Started 

After all containers have started, access the Dashboard at http://localhost:8501 in your browser.

Installation (Client Only)

These instructions help you launch the standalone Hummingbot client.

Clone Repo

Open a terminal and run the following commands to clone the Hummingbot Github repo and enter the root folder:

  git clone https://github.com/hummingbot/hummingbot.git
  cd hummingbot

Launch Hummingbot Container

  docker compose up -d

This will start to download the latest Hummingbot image if it's not already on your system.

Attach to Instance

The -d flag runs Hummingbot in detached mode. Attach to it by running the command:

  docker attach hummingbot

You should now see the Hummingbot welcome screen:

To get started with Hummingbot, check out the following pages and guides:

• Basic Features
• V2 Strategy Walkthough
• Hummingbot FAQ

Advanced Configurations

Autostart Strategy

This configures a Hummingbot instance to automatically start a script or strategy when the Docker instance is instantiated.

Uncomment the following lines in the docker-compose.yml:

Show Configuration

  environment:
    - CONFIG_PASSWORD=a       # Replace "a" with your Hummingbot password
    - CONFIG_FILE_NAME=simple_pmm_example.py    # Replace with your script filename
    - SCRIPT_CONFIG=conf_simple_pmm_example.yaml   # Replace with your script config file (or leave commented)

Afterwards, stop the instance with docker compose down and re-launch it with docker compose up -d. When you attach to the instance, your strategy should already be running.

Hummingbot + Gateway

Gateway is API middleware that helps Hummingbot connect to DEXs on various blockchains. To launch Hummingbot with Gateway, uncomment the Gateway section of docker-compose.yml, except for the environment lines:

Show Configuration

gateway:
  container_name: gateway
  image: hummingbot/gateway:latest
  ports:
    - "15888:15888"
    - "8080:8080"
  volumes:
    - "./gateway_files/conf:/home/gateway/conf"
    - "./gateway_files/logs:/home/gateway/logs"
    - "./gateway_files/db:/home/gateway/db"
    - "./certs:/home/gateway/certs"
  environment:
    - GATEWAY_PASSPHRASE=a

Afterwards, follow the instructions in Gateway - Installation to generate certificates and connect Gateway to Hummingbot.

Multiple Hummingbot Instances

This configuration launches two Hummingbot Docker instances with the container names hummingbot-1 and hummingbot-2. To use it, replace the content of docker-compose.yml in your Hummingbot root folder with the code below.

Show Configuration

```yaml services: hummingbot: container_name: hummingbot-1 image: hummingbot/hummingbot:latest volumes: - ./conf:/home/hummingbot/conf - ./conf/connectors:/home/hummingbot/conf/connectors - ./conf/strategies:/home/hummingbot/conf/strategies - ./conf/controllers:/home/hummingbot/conf/controllers - ./conf/scripts:/home/hummingbot/conf/scripts - ./logs:/home/hummingbot/logs - ./data:/home/hummingbot/data - ./certs:/home/hummingbot/certs - ./scripts:/home/hummingbot/scripts - ./controllers:/home/hummingbot/controllers logging: driver: "json-file" options: max-size: "10m" max-file: "5" tty: true stdin_open: true network_mode: host # environment: # - CONFIG_PASSWORD=a # - CONFIG_FILE_NAME=simple_pmm_example.py # - SCRIPT_CONFIG=conf_simple_pmm_example.yaml services: hummingbot-2: container_name: hummingbot-2 image: hummingbot/hummingbot:latest volumes: - ./conf:/home/hummingbot/conf - ./conf/connectors:/home/hummingbot/conf/connectors - ./conf/strategies:/home/hummingbot/conf/strategies - ./conf/controllers:/home/hummingbot/conf/controllers - ./conf/scripts:/home/hummingbot/conf/scripts - ./logs:/home/hummingbot/logs - ./data:/home/hummingbot/data - ./certs:/home/hummingbot/certs - ./scripts:/home/hummingbot/scripts - ./controllers:/home/hummingbot/controllers logging: driver: "json-file" options: max-size: "10m" max-file: "5" tty: true stdin_open: true network_mode: host # environment: # - CONFIG_PASSWORD=a # - CONFIG_FILE_NAME=simple_pmm_example.py # - SCRIPT_CONFIG=conf_simple_pmm_example.yaml ```

Note that the above configuration has both bots sharing the hummingbot folder, which is where configs, logs, and databases are stored. If you want to set a different folder for hummingbot-2, set volumes to a different folder path, such as hummingbot_files_2.

Attach to instance 1:

  docker attach hummingbot-1

Attach to instance 2:

  docker attach hummingbot-2

Hummingbot + Gateway + Broker

This configuration starts instances of Hummingbot, Gateway, and EMQX Broker. To use it, replace the content of the docker-compose.yml in your Hummingbot root folder with the code below.

Show Configuration

```yaml services: hummingbot: container_name: hummingbot image: hummingbot/hummingbot:latest # build: Uncomment this and comment image if you want to build it locally # context: . # dockerfile: Dockerfile volumes: - ./conf:/home/hummingbot/conf - ./conf/connectors:/home/hummingbot/conf/connectors - ./conf/strategies:/home/hummingbot/conf/strategies - ./conf/controllers:/home/hummingbot/conf/controllers - ./conf/scripts:/home/hummingbot/conf/scripts - ./logs:/home/hummingbot/logs - ./data:/home/hummingbot/data - ./certs:/home/hummingbot/certs - ./scripts:/home/hummingbot/scripts - ./controllers:/home/hummingbot/controllers logging: driver: "json-file" options: max-size: "10m" max-file: "5" tty: true stdin_open: true network_mode: host # environment: # - CONFIG_PASSWORD=a # - CONFIG_FILE_NAME=simple_pmm_example.py # - SCRIPT_CONFIG=conf_simple_pmm_example.yaml gateway: container_name: gateway image: hummingbot/gateway:latest ports: - "15888:15888" - "8080:8080" volumes: - "./gateway_files/conf:/home/gateway/conf" - "./gateway_files/logs:/home/gateway/logs" - "./gateway_files/db:/home/gateway/db" - "./certs:/home/gateway/certs" environment: - GATEWAY_PASSPHRASE=a emqx: container_name: "emqx" image: emqx:5 restart: unless-stopped environment: - EMQX_NAME=emqx - EMQX_LOADED_PLUGINS="emqx_recon,emqx_retainer,emqx_management,emqx_dashboard" volumes: - emqx-data:/opt/emqx/data - emqx-log:/opt/emqx/log - emqx-etc:/opt/emqx/etc ports: - "1883:1883" # MQTT TCP - "8883:8883" # MQTT TCP SSL - "8083:8083" # MQTT WebSocket - "8084:8084" # MQTT WebSocket SSL - "8081:8081" # HTTP Management API - "18083:18083" # HTTP Dashboard - "61613:61613" # Web-STOMP Gateway healthcheck: test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"] interval: 5s timeout: 25s retries: 5 volumes: emqx-data: emqx-log: emqx-etc:

</details>

After starting the instance, follow the [Gateway instructions](/gateway/installation/) to generate certificates and set your Gateway passphrase.

To configure the EMQX Broker, attach to the `emqx` instance:


```bash
  docker attach emqx

To configure authentication and available ports, navigate to the EMQX dashboard at . The default credentials are: `admin:public`. To connect to your bots via MQTT, leave the `mqtt_username` and `mqtt_password` parameters of the bot empty.