# Freqtrade tutorial: Docker setup, dry run and FreqUI

URL: https://fincodelabs.com/en/blog/freqtrade-tutorial · Publisher: Fincode (Fincode Yazılım ve Teknoloji A.Ş.), Istanbul, Turkey · Category: Trading bots · Published: 2026-11-06 · Updated: 2026-11-06

Freqtrade tutorial tested on 5 and 6 November 2026: Docker Compose commands, a dry-run config with no keys, safe FreqUI access and the failures you meet.

**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
```

**What each step did on 5 and 6 November 2026**

| Step | Result here |
| --- | --- |
| `docker compose pull` | Image of 311 MB compressed, shown as 1.33 GB by `docker images`; the docs' recommended minimum is 1 GB of disk, so allow more |
| `create-userdir` | Created `user_data` with `strategies`, `data`, `logs`, `backtest_results`, `notebooks` and others, plus `sample_strategy.py` |
| `new-config` | Needs a terminal: with `docker compose run -T` it stopped with an `EOFError` |
| `up -d` | The API answered after 10 seconds on 6 November and about 40 on 5 November, when a market-data request timed out; wait for the `Uvicorn running` log line |

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:

```json
{
  "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](https://fincodelabs.com/en/blog/api-key-security-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.

> **Reading the simulated balance (not money, not a result).** `/api/v1/balance` returned a USDT balance of 1,000 with the note `Simulated balances`, and a `bot_owned` figure of 990. That is 1,000 x 0.99, because the generated config sets `tradable_balance_ratio` to 0.99, so the bot counts only 990 as its own to trade.

The docs list these simplifications:

**Dry-run behavior per the configuration page, read 6 November 2026**

| Item | In a dry run |
| --- | --- |
| Market orders | Filled from order book volume when placed, with slippage capped at 5% |
| Limit orders | Filled once price reaches the level, or time out under `unfilledtimeout` |
| Stop on exchange | The stop price is assumed to fill |
| Restarts | Open orders are assumed not to have filled while the bot was offline |

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](https://fincodelabs.com/en/blog/backtesting-trading-strategy-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:

**FreqUI and REST checks, 5 and 6 November 2026**

| Setup | Result from the host |
| --- | --- |
| `listen_ip_address` 0.0.0.0, mapping 127.0.0.1:8080:8080 | `/api/v1/ping` returned pong; `/` returned the FreqUI page |
| Same, `/api/v1/version` without login | HTTP 401; with login, 2026.10 |
| `listen_ip_address` 127.0.0.1, same mapping | `curl` exit 52, Empty reply from server, while a request inside the container worked |

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.

**Work that usually goes beyond configuration**

| Need | What it involves |
| --- | --- |
| Custom code | Translating your own written rules into a strategy class and callbacks, with tests |
| Connectors | Venues outside the supported list rely on CCXT, and the docs do not guarantee they work |
| Monitoring | Health checks, webhook alerts and a person who responds, plus the limits in [trading bot risk management](https://fincodelabs.com/en/blog/trading-bot-risk-management) |
| Operations | A Linux host, time sync, backups of `user_data`, a pinned image and an upgrade routine |

For integration work in general, see Fincode's [algorithmic trading](https://fincodelabs.com/en/services/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)](https://www.freqtrade.io/en/stable/docker_quickstart/)
- [Freqtrade documentation: Home (disclaimer, supported exchanges, requirements)](https://www.freqtrade.io/en/stable/)
- [Freqtrade documentation: Configuration (dry run, production mode, environment variables)](https://www.freqtrade.io/en/stable/configuration/)
- [Freqtrade documentation: REST API (port mapping, exposure warnings)](https://www.freqtrade.io/en/stable/rest-api/)
- [Freqtrade documentation: FreqUI](https://www.freqtrade.io/en/stable/freq-ui/)
- [Freqtrade documentation: Bot basics (loop, callbacks, backtesting differences)](https://www.freqtrade.io/en/stable/bot-basics/)
- [Freqtrade documentation: Strategy customization](https://www.freqtrade.io/en/stable/strategy-customization/)
- [Freqtrade documentation: Exchange notes](https://www.freqtrade.io/en/stable/exchanges/)
- [Freqtrade documentation: FAQ (no trades yet, wrong system time)](https://www.freqtrade.io/en/stable/faq/)
- [Freqtrade on GitHub: README, license and default branch](https://github.com/freqtrade/freqtrade)
- [Freqtrade releases on GitHub (2026.10, 2026.9, 2026.8)](https://github.com/freqtrade/freqtrade/releases)
- [Freqtrade docker-compose.yml, stable branch](https://github.com/freqtrade/freqtrade/blob/stable/docker-compose.yml)
- [Docker Hub: freqtradeorg/freqtrade tags](https://hub.docker.com/r/freqtradeorg/freqtrade/tags)
- [Freqtrade LICENSE file: GNU General Public License version 3 text](https://raw.githubusercontent.com/freqtrade/freqtrade/develop/LICENSE)
- [Capital Markets Law No. 6362, Article 99/A (Turkish, consolidated text)](https://www.mevzuat.gov.tr/mevzuatmetin/1.5.6362.pdf)

> 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](https://fincodelabs.com/en/editorial-policy).

---

Published by Fincode (Fincode Yazılım ve Teknoloji A.Ş.), a software company in Istanbul, Turkey: https://fincodelabs.com/en/blog/freqtrade-tutorial

Cite as: Fincode, "Freqtrade tutorial: Docker setup, dry run and FreqUI", updated November 6, 2026, https://fincodelabs.com/en/blog/freqtrade-tutorial