Freqtrade tutorial: Docker setup, dry run and FreqUI

Short answer: This Freqtrade tutorial runs the bot in Docker with no real orders: fetch the official Compose file, pull the image, create user_data, generate a dry-run config with no API keys, then start it and open FreqUI on localhost. Every step ran on 5 November 2026 with release 2026.10 and again on 6 November; the bot ran in simulation and opened no trade. Freqtrade is GPL-3.0 software whose own README calls it educational, and a dry run shows how it behaves, not what it would earn.

The official docs spread these steps over several pages. This guide puts them in order and adds what happened when they ran on 5 and 6 November 2026: Docker 29.4.0 and Compose 5.1.1 on Windows 11, image freqtradeorg/freqtrade:stable, which reported Freqtrade 2026.10, Python 3.14.10 and CCXT 4.5.90.

A config needs a venue and a pair, so the run read public market data from one listed exchange (Kraken) for one pair (BTC/USDT), with no account, no key and no order. The strategy was the SampleStrategy file the project ships as an example, used only to start the loop. Nothing here recommends an exchange, a pair or a setting, and automated trading can lose money.

Freqtrade Docker setup: the commands that ran

Nine commands take you from an empty folder to a running dry-run bot, all from the official Docker quickstart.

mkdir ft_userdata
cd ft_userdata
curl https://raw.githubusercontent.com/freqtrade/freqtrade/stable/docker-compose.yml -o docker-compose.yml
docker compose pull
docker compose run --rm freqtrade create-userdir --userdir user_data
docker compose run --rm freqtrade new-config --config user_data/config.json
docker compose up -d
docker compose ps
docker compose logs -f

Use up -d rather than run for the trade command: the docs say it starts the container properly, including port forwarding, and restarts it after a reboot. To update, the docs say to run docker compose pull and up -d again and to check the changelog for breaking changes. Releases have been about monthly (31 August, 29 September and 30 October 2026, per GitHub), and 2026.8 turned on @informative call caching by default, so a pinned tag such as freqtradeorg/freqtrade:2026.10 is safer than stable once you depend on behavior.

The Freqtrade docker-compose.yml, explained

The official file defines one service, and the line that matters most is the port mapping, which binds the API to localhost.

services:
  freqtrade:
    image: freqtradeorg/freqtrade:stable
    restart: unless-stopped
    container_name: freqtrade
    volumes:
      - "./user_data:/freqtrade/user_data"
    ports:
      - "127.0.0.1:8080:8080"     # localhost only; do not change to 8080:8080
    command: >
      trade
      --logfile /freqtrade/user_data/logs/freqtrade.log
      --db-url sqlite:////freqtrade/user_data/tradesv3.sqlite
      --config /freqtrade/user_data/config.json
      --strategy SampleStrategy

Comments are removed here, except one added on the port line. The commented-out options in the real file switch to develop or plotting images, add a GPU section for FreqAI, the project's machine learning module, or build a custom image. Plot and FreqAI variants exist as tags such as stable_plot and stable_freqai; Docker Hub listed them at 323 MB and 723 MB compressed (amd64), read 6 November 2026. The file mounts ./user_data, so your config, strategies, logs and tradesv3.sqlite survive a container rebuild and are what you back up.

A Freqtrade dry-run config with no API keys

Set dry_run to true and leave the key fields empty: the docs say keys are optional in a dry run and only read-only operations reach the exchange.

new-config asks at least nine questions, and three more if you enable the REST API. Its defaults, read from the 2026.10 source, are dry-run on, stake currency USDT, stake amount unlimited, 3 open trades and the REST API off, so answer yes to the API question if you want FreqUI. It also generates a random JWT key and WebSocket token. It writes a VolumePairList by default, and the docs ask you to check options such as pricing and the pairlist before starting. The run below replaced it with a static list. Since 2026.8 the key field is api_key; the older key is deprecated. This shortened form shows the fields that matter, with placeholders for you to replace:

{
  "dry_run": true,
  "dry_run_wallet": 1000,
  "stake_currency": "USDT",
  "stake_amount": 100,
  "max_open_trades": 1,
  "trading_mode": "spot",
  "exchange": {
    "name": "EXCHANGE_ID_FROM_THE_DOCS",
    "api_key": "",
    "secret": "",
    "pair_whitelist": ["BASE/QUOTE"]
  },
  "pairlists": [{"method": "StaticPairList"}],
  "api_server": {
    "enabled": true,
    "listen_ip_address": "0.0.0.0",
    "listen_port": 8080,
    "username": "CHANGE_ME",
    "password": "CHANGE_ME",
    "jwt_secret_key": "RANDOM_VALUE_OF_32_OR_MORE_CHARACTERS",
    "ws_token": "RANDOM_VALUE"
  }
}

With an exchange and pair set, this form passed freqtrade show-config on 6 November; a 17-character JWT placeholder failed with is too short, since the schema requires 32. The real config also holds pricing and timeout blocks from new-config, so edit that file rather than pasting this one. Never put real keys in a file you share; the docs offer FREQTRADE__ environment variables for secrets, and API key security for trading bots covers permissions and storage. Should you ever switch modes, the docs say to use a fresh database so simulated trades do not affect real statistics.

What a Freqtrade dry run actually simulates

A dry run reads live market data and simulates orders and balances, so it tests the software's behavior but not real fills.

The log confirmed the mode (Runmode set to dry_run, then Dry run is enabled). No simulated trade opened in either run, each a few minutes long, which the FAQ treats as normal, since a strategy may wait hours or days for an entry.

The docs list these simplifications:

Queue position, rejected orders, latency and exchange outages are not in that list, so treat a clean dry run as a check of the plumbing, not of fills. Why simulated results flatter strategies is covered in backtesting pitfalls.

Freqtrade UI: reach FreqUI without exposing it

FreqUI is served by the bot itself on port 8080, and you should reach it through localhost, an SSH tunnel or a VPN, never directly from the internet.

The docs strongly recommend against exposing the API to the internet and say FreqUI does not support HTTPS out of the box. Two Docker settings look contradictory and are not: inside the container the bot listens on 0.0.0.0, and the Compose mapping limits access to the host's 127.0.0.1. Each was tested:

The docs warn that a mapping of 8080:8080 or 0.0.0.0:8080:8080 lets anyone who can reach that port talk to the API. The bot's own warning will not catch this: the 2026.10 source skips its external-listening security warning when it detects Docker, and none appeared in the logs. That mapping was not run here. The docs advise a strong password and a random jwt_secret_key of 32 or more characters.

Where a Freqtrade setup fails: Windows, clocks and networks

Most early failures here came from the host rather than the bot, and the docs do not recommend Docker on Windows for production.

• Clock drift. The 5 November run logged a -1.5 s deviation from the exchange's clock; the 6 November run did not. The check, added in 2026.9, warns above 1.5 s, and the README says the clock must be synchronized to NTP very frequently. For the recvWindow error on Windows, the docs give wsl --shutdown and a Docker restart as a temporary fix, and a Linux host or scheduled WSL restarts as the lasting one.
• Timeouts. The first run logged RequestTimeout on the markets and candle calls and recovered through built-in retries; the second had none. Watch for repeats, not single lines.
• Empty FreqUI. The REST API question defaults to no, and a CORS error at login means the UI runs on a different port than the API without a CORS setting, per the FreqUI page.
• Exchange rules. The exchange notes list venue-specific requirements, and availability depends on where you are.

The docs suggest a Linux server for reliable operation, with at least 2 GB of RAM and 2 vCPUs. The container used about 290 MiB while idle in both runs, with one pair. Freqtrade also lists futures on some venues, but futures are a separate regulated question and this guide stays on spot dry-run. For readers in Turkey, Article 99/A of Capital Markets Law No. 6362 treats activity by foreign crypto-asset platforms directed at Turkish residents as unauthorized.

How a Freqtrade bot is structured

A bot is one Python strategy class plus a config, run by a loop that repeats every few seconds while new data arrives once per candle.

1. Strategy file. A class in user_data/strategies with populate_indicators, populate_entry_trend and populate_exit_trend, each working on a pandas dataframe. Freqtrade finds it by class name, not file name.
2. Loop. Each iteration loads open trades, refreshes the pairlist, downloads candles when a new one is due, analyzes pairs, updates orders, checks exits, then checks entries. The throttle is internals.process_throttle_secs, 5 seconds in the generated config.
3. Callbacks. Hooks such as custom_stoploss and custom_exit run for each open trade every iteration live (roughly every 5 seconds), but at most once per candle in backtesting, which the docs warn can cause mismatches.
4. Control. Telegram, the REST API and webhooks. /api/v1/health returned the last process time here, so an external monitor can alert when it stops moving.

Freqtrade on GitHub, GPL-3.0 and where developers come in

The repository is freqtrade/freqtrade under GPL-3.0, with release 2026.10 published on 30 October 2026.

The default branch is develop; use stable or a tag. Under the GPL-3.0 text in the repository, you may make and run modified copies without conditions as long as you do not convey them, and conveying means any propagation that lets other parties make or receive copies. If you convey a modified version, for example to a client, the whole work must be licensed to them under the GPL, and conveying object code means also conveying its Corresponding Source, in one of the ways Section 6 lists. Whether a strategy that imports Freqtrade is a covered work is a question for a lawyer before you ship one to clients. This is not legal advice.

For integration work in general, see Fincode's algorithmic trading page; naming Freqtrade or Kraken here does not mean Fincode integrates them or has built on them. Fincode works from rules the customer wrote and does not supply strategies.

Frequently asked questions

Is Freqtrade free?

The software is free and open source under GPL-3.0. You still pay for your own server and any exchange fees if you ever trade live, and trades can lose money.

Do I need API keys for a Freqtrade dry run?

No. The configuration page says API keys may or may not be provided in a dry run, and only read-only operations run on the exchange. Both test runs used empty key fields.

Can I run Freqtrade in Docker on Windows?

It ran on Windows 11 in both tests, with a clock warning on 5 November. The docs suggest Docker on Windows only for experiments, data download and backtesting, and a Linux server for reliable trading.

Which Python version does Freqtrade need?

Python 3.12 or later per the documentation, though the 2026.10 install scripts accept only 3.12 to 3.14 (read 6 November 2026); 2026.10 dropped 3.11. The Docker image used here shipped Python 3.14.10, so Docker users do not manage it.

Sources

• Freqtrade documentation: Docker quickstart (commands, Windows notes, updating) (opens in a new tab)
• Freqtrade documentation: Home (disclaimer, supported exchanges, requirements) (opens in a new tab)
• Freqtrade documentation: Configuration (dry run, production mode, environment variables) (opens in a new tab)
• Freqtrade documentation: REST API (port mapping, exposure warnings) (opens in a new tab)
• Freqtrade documentation: FreqUI (opens in a new tab)
• Freqtrade documentation: Bot basics (loop, callbacks, backtesting differences) (opens in a new tab)
• Freqtrade documentation: Strategy customization (opens in a new tab)
• Freqtrade documentation: Exchange notes (opens in a new tab)
• Freqtrade documentation: FAQ (no trades yet, wrong system time) (opens in a new tab)
• Freqtrade on GitHub: README, license and default branch (opens in a new tab)
• Freqtrade releases on GitHub (2026.10, 2026.9, 2026.8) (opens in a new tab)
• Freqtrade docker-compose.yml, stable branch (opens in a new tab)
• Docker Hub: freqtradeorg/freqtrade tags (opens in a new tab)
• Freqtrade LICENSE file: GNU General Public License version 3 text (opens in a new tab)
• Capital Markets Law No. 6362, Article 99/A (Turkish, consolidated text) (opens in a new tab)

This guide is general information about software and markets, not investment, legal or tax advice. Automated trading can lose money, past or backtested performance does not guarantee future results, and the rules that apply depend on your jurisdiction and your exchange's terms. Sources, checks and corrections: see the editorial policy.