Hummingbot: a Python framework for running market-making and arbitrage bots across 140+ venues

What Hummingbot solves, and who ends up using it

Hummingbot is not a bot. It is a framework for writing one. The README describes it as "an open-source framework that helps you design and deploy automated trading strategies, or bots, that can run on many centralized or decentralized exchanges." That framing matters, because the work it removes is connector work: quoting, cancelling, tracking order state and reconciling fills against a venue's API is the part that eats weeks before any strategy logic exists.

The intended audience is a developer who is comfortable in Python and wants to express a market-making or arbitrage idea as code. The README's own mission statement is to "democratize high-frequency trading" by building a community of algorithmic traders who share and contribute code. The repository is organised around that: scripts, controllers and executors are the three extension points, and each is a place to put your own logic rather than a fixed product you configure.

If you are looking for a finished strategy you switch on and fund, this is the wrong shape of project. The README's own examples are a basic market-making script and a full-featured market-making controller, not a menu of profitable presets. The framework gives you the plumbing and the execution primitives; the edge is still yours to write.

Scripts, controllers and executors: the three layers of a Hummingbot strategy

The README lays out three frameworks. Scripts are single-file Python strategies, described as "the easiest way to build and customize your own bot," with scripts/simple_pmm.py as the reference example. Controllers are reusable V2 strategies whose configs "can be backtested, deployed, and tuned live while running," with controllers/generic/pmm_mister.py as the example. Executors are the lowest layer: self-contained building blocks that manage order lifecycles for common patterns, and the README names position, DCA, grid, arbitrage, XEMM, TWAP and LP, pointing at position_executor as the example.

The layering is the design decision worth understanding. An executor owns one order lifecycle, so a position executor knows how to enter, manage and exit a position without you reimplementing that state machine. A controller composes executors into a strategy and exposes settings that can change while the bot runs. A script is the escape hatch when neither fits. That is a sensible progression, and it means the amount of code you write scales with how unusual your strategy is.

The constraint is that the layers are not interchangeable in operation. A controller's live-tunable config is a property of the V2 controller machinery, not of scripts. If you write a script, you have given up live tuning and backtesting through the controller path, and you are maintaining a single file that the framework will not help you evolve.

Installing Hummingbot and running a paper-trading bot with the hbot CLI

The README calls the hbot command-line interface "the recommended way to run the Hummingbot client directly," installed from source, and it requires Anaconda or Miniconda. The commands below are copied from the README's source-install section: clone, run make install to create the conda environment and build extensions, activate it, then check the CLI responds.

# Clone the repository
git clone https://github.com/hummingbot/hummingbot.git
cd hummingbot

# Create the conda environment, build extensions, and expose the `hbot` CLI
make install

# Activate the environment
conda activate hummingbot
hbot --help

If you want hbot available outside the conda environment, the README gives make link-cli to add it to your host PATH. On first use, hbot asks for a keystore password that encrypts your exchange API keys; set HBOT_PASSWORD or pass --password-stdin for non-interactive use such as scripts or agent workflows.

The first useful thing to run needs no exchange credentials at all. The README's simple_pmm paper-trading script simulates trading against live Binance market data, so you can exercise the full create, start, status, stop cycle before any key exists.

hbot create simple_pmm --name conf_paper_bot.yml \
     --set exchange=binance_paper_trade --set trading_pair=BTC-USDT
hbot start conf_paper_bot.yml                          # run it (one bot per install)
hbot status                                            # check on it
hbot stop                                              # stop gracefully

Note the comment the README attaches to hbot start: one bot per install. That is not incidental, and it is the single most important operational fact on this page. Going live means storing real keys and running a controller instead of a script:

hbot connect binance                                   # store API keys (encrypted)
hbot create pmm_mister --name conf_my_bot.yml \
     --set connector_name=binance --set trading_pair=BTC-USDT --set total_amount_quote=100
hbot start conf_my_bot.yml                             # run it (one bot per install)

The Docker path is deliberately command-compatible. After git clone, make setup (answer y to "Include Gateway?" if you want the DEX middleware), make deploy, then make link-cli, which installs a wrapper that runs hbot inside the container. The README states that every command above is identical whether you installed from source or Docker. If you skip the wrapper, docker exec -it hummingbot hbot <command> does the same job. To dedicate the container to hbot rather than the interactive client, uncomment command: tail -f /dev/null in docker-compose.yml before make deploy.

One bot per install, and the zombie problem the compose file admits to

The one-bot-per-install rule is the limitation with the widest consequences. Running a market-making controller on Binance and an arbitrage strategy on another venue means two installations, two sets of logs, two keystore files and two upgrade paths. Nothing in the README suggests the CLI can multiplex, and the docker-compose.yml comment reinforces the point by describing a mode where "one dedicated bot" becomes the container's main process via command: hbot start <config> --foreground.

The compose file also documents a failure mode that only appears when you mix hbot with Docker. The init: true line is annotated to explain that it "runs a real init (tini) as PID 1 so it REAPS exited children." The comment states this is needed when a bot is started with docker exec ... hbot start, because the process reparents to PID 1 when the exec returns, and without an init it "lingers as a zombie that makes hbot stop wait its full timeout." The file calls it harmless otherwise. That is a specific, mechanical trap: if you build your own compose file from scratch without init: true and drive bots through docker exec, hbot stop will appear to hang.

A second constraint is the build itself. setup.py compiles Cython extensions, and the Dockerfile runs python3 setup.py build_ext --inplace -j 8 before deleting the generated .cpp files. Source installs therefore need a working compiler toolchain; make install is not a pure-Python pip step. The build system pins cython>=3.0.12 and numpy>=2.2.6. If your environment cannot compile extensions, the Docker image is the practical route.

How Hummingbot compares with Freqtrade and CCXT

The comparison people search for most is Hummingbot versus Freqtrade. The difference is the target workload. Hummingbot's extension points are executors for order lifecycle management, and the README's named patterns are position, DCA, grid, arbitrage, XEMM, TWAP and LP. That is a market-making and execution toolkit, where the bot is continuously quoting both sides of a book and managing inventory. Freqtrade is a signal-driven backtesting and execution framework built around indicators and entry and exit rules. If your idea is "buy when this indicator crosses that one," Hummingbot's executor layer is not aimed at you, and you would be writing a script to emulate a workflow another tool already models.

The CCXT comparison is different in kind. CCXT is a library that normalises exchange APIs; it gives you uniform methods for placing and reading orders and stops there. Hummingbot is an application built on top of exchange connectivity that adds strategy composition, an order lifecycle model, a CLI, a keystore for encrypted API keys and a Docker deployment path. Using CCXT means writing your own bot loop and your own state reconciliation. Using Hummingbot means accepting its loop and its layering. The honest framing is that CCXT is a dependency you could build a Hummingbot-shaped thing on, not a peer of it.

One thing the README does not settle: it advertises 140+ trading venues, but the connector list is not reproduced in the README, and setup.py explicitly excludes two Injective data source packages from the build. Confirm your venue exists before designing around it.

Licence, releases and what an upgrade actually costs

Hummingbot is Apache-2.0, and the README states the codebase is "free and publicly available under the Apache 2.0 open-source license." For a trading bot this matters less than it sounds. Apache-2.0 permits commercial use and modification, and it includes a patent grant, but it also means there is no vendor to hold responsible for a strategy losing money. That is a legal fact about the licence, not a judgement about the software, and it is not legal advice; if you plan to redistribute a modified Hummingbot, read the licence text in LICENSE yourself.

On cadence, the release history shows v2.14.0 on 2026-04-21, v2.15.0 on 2026-06-16 and v2.16.0 on 2026-07-29, with the last push to master on 2026-09-09. That is a project shipping roughly every six to eight weeks, and the repository is not archived.

The upgrade cost is where the layering pays off or does not. If you built on controllers and executors, your strategy sits above the framework and an upgrade is mostly a rebuild: pull, run make install again, and the Cython extensions are recompiled. setup.py carries a version string (20260729) and the Dockerfile bakes in BRANCH, COMMIT and BUILD_DATE labels, so image provenance is traceable. If you forked connector code or patched internals, every upgrade is a merge. The README gives no rollback procedure and no version-pinning guidance for the conda environment, so treat your own conf directory as the thing to back up, since docker-compose.yml mounts conf, logs, data and certs as volumes precisely so container replacement does not destroy them.

Condor, agentic strategies and where the AI story actually sits

The README opens its getting-started section with Condor, described as "the AI harness for building and running agentic strategies and bot instances" that connects LLM-powered decision-making to deterministic trade execution via the Hummingbot API, controlled through Telegram or a web dashboard. It links to condor.hummingbot.org and lives in a separate repository, hummingbot/condor.

That separation is the useful detail. Condor is not part of this codebase; it is a consumer of the Hummingbot API. So an evaluation of Hummingbot does not depend on whether you believe an LLM should choose trades. The framework's job is unchanged: hold the order state, talk to the venue, execute deterministically. If you want an agent in the loop, Condor is the layer that supplies it, and the hbot CLI is designed to be driven by such a thing, which is why the README offers --password-stdin and HBOT_PASSWORD for non-interactive use.

The same API is what a dashboard would talk to. The README's quick links include a reported-volumes site, but the README does not document a bundled dashboard in this repository, so treat "hummingbot dashboard" as a question about the API surface rather than a feature you can expect to find installed.

Editorial conclusion

Adopt Hummingbot if you write Python, want a strategy framework rather than a single fixed bot, and can accept one running bot per install with a conda and Cython build behind it. Do not adopt it if you want a point-and-click product, or if you need several concurrent bots from one process. Before committing capital, verify three things in order: that the paper-trading path works with hbot create simple_pmm and the binance_paper_trade connector, that your exchange appears among the connectors you actually need, and that the strategy you intend to run exists as a controller or executor rather than only as a script you would have to write yourself.

Frequently asked questions

Official sources

1. hummingbot/hummingbot on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases