Freqtrade User Guide

Freqtrade is a free, open-source cryptocurrency trading bot written in Python. It connects to your exchange account through the ccxt library, runs your trading strategy against live market data, and places real or simulated orders on your behalf. You control it from the command line, from Telegram, from a built-in web UI (FreqUI), or over a REST API.

This guide covers everything you need to install Freqtrade, configure it safely, write and test a strategy, run it in simulation and in production, and operate it day to day. Everything documented here is derived directly from the source code at the version stamped in the footer.

Important

Trading cryptocurrency carries significant financial risk. Freqtrade defaults to dry-run (simulation) mode for good reason. Run in dry-run until you fully understand your strategy's behavior, and never trade with money you cannot afford to lose.

Table of Contents

1. Quick Start
2. Requirements
3. Installation
4. Your First Configuration
5. The Command-Line Interface
6. Everyday Usage
7. Writing a Strategy
8. Downloading Market Data
9. Backtesting
10. Hyperopt — Optimizing Your Strategy
11. Controlling the Bot: Telegram
12. Controlling the Bot: REST API & FreqUI
13. Pairlists — Choosing What to Trade
14. Protections — Guarding Your Capital
15. FreqAI — Machine Learning
16. Futures & Leverage Trading
17. Plotting & Analysis
18. Common Workflows
19. Troubleshooting
20. Frequently Asked Questions
21. Command Reference

1. Quick Start

The fastest way to get a bot running in simulation mode (no real money) on Linux/macOS:

# 1. Clone and install
git clone https://github.com/freqtrade/freqtrade.git
cd freqtrade
./setup.sh -i

# 2. Activate the virtual environment
source .venv/bin/activate

# 3. Create your user directory (strategies, data, configs live here)
freqtrade create-userdir --userdir user_data

# 4. Generate a configuration interactively
freqtrade new-config --config user_data/config.json

# 5. Download some historical data to play with
freqtrade download-data --config user_data/config.json --timerange 20240101- --timeframes 5m

# 6. Backtest the bundled sample strategy
freqtrade backtesting --config user_data/config.json --strategy SampleStrategy

# 7. Start trading in dry-run (simulation) mode
freqtrade trade --config user_data/config.json --strategy SampleStrategy

Note

Step 4 produces a config with "dry_run": true. In this mode Freqtrade simulates every order against live prices but never sends a real order to the exchange. This is the correct way to evaluate a strategy before risking funds.

The same flow works on Windows using setup.ps1 (PowerShell) instead of setup.sh, or you can use Docker (see Installation).

2. Requirements

Tip

Run freqtrade list-exchanges after installation to see every exchange Freqtrade recognizes, and freqtrade list-exchanges --all to see everything ccxt supports (including exchanges not validated by Freqtrade).

Core dependencies

Freqtrade builds on a well-known Python stack. You do not install these by hand — they come from the requirements files — but knowing them helps you reason about behavior:

3. Installation

Freqtrade offers three installation paths. Docker is recommended for most users because it isolates the build toolchain.

Docker (recommended)

git clone https://github.com/freqtrade/freqtrade.git
cd freqtrade
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

The bundled compose file mounts ./user_data into the container and exposes the API on 127.0.0.1:8080 (localhost only). The default image is freqtradeorg/freqtrade:stable; a FreqAI+PyTorch variant freqtradeorg/freqtrade:stable_freqaitorch is also published.

Script (Linux / macOS)

git clone https://github.com/freqtrade/freqtrade.git
cd freqtrade
./setup.sh -i        # install from scratch
source .venv/bin/activate

setup.sh detects your OS (Debian/Ubuntu, RedHat/CentOS, macOS), installs system build dependencies, creates a .venv virtual environment, installs Python requirements, and runs freqtrade install-ui to fetch FreqUI. If uv is installed it is used automatically for faster installs.

Script (Windows)

git clone https://github.com/freqtrade/freqtrade.git
cd freqtrade
.\setup.ps1

The PowerShell script finds a supported Python (3.11–3.14), creates .venv, lets you pick which requirement files to install, runs pip install -e ., and installs FreqUI.

Manual (pip)

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip wheel setuptools
pip install -r requirements.txt
pip install -e .
freqtrade install-ui

Optional dependency groups

The setup script asks which feature groups you want. You can install them manually too:

Warning

hyperopt, plot, and freqai are not installed by the core requirements.txt. If you run freqtrade hyperopt without the hyperopt dependencies, Freqtrade raises an error telling you to install them. Install the matching requirements file first.

Updating

# Script install
./setup.sh -u          # git pull + reinstall dependencies

# Docker
docker compose pull && docker compose up -d

Verify the install

freqtrade --version

freqtrade 2026.6

4. Your First Configuration

Freqtrade is driven by a JSON configuration file (default name config.json). The interactive builder is the easiest start:

freqtrade new-config --config user_data/config.json

It asks you a series of questions (exchange, stake currency, stake amount, whether to enable Telegram/API, etc.) and writes a ready-to-edit file. You can also copy one of the bundled examples from config_examples/ (config_binance.example.json, config_kraken.example.json, config_freqai.example.json, config_full.example.json).

A minimal working config

Below is a real, source-based minimal Binance configuration (dry-run, spot):

{
    "$schema": "https://schema.freqtrade.io/schema.json",
    "max_open_trades": 3,
    "stake_currency": "USDT",
    "stake_amount": 30,
    "tradable_balance_ratio": 0.99,
    "fiat_display_currency": "USD",
    "timeframe": "5m",
    "dry_run": true,
    "cancel_open_orders_on_exit": false,
    "unfilledtimeout": {
        "entry": 10,
        "exit": 10,
        "exit_timeout_count": 0,
        "unit": "minutes"
    },
    "entry_pricing": {
        "price_side": "same",
        "use_order_book": true,
        "order_book_top": 1
    },
    "exit_pricing": {
        "price_side": "same",
        "use_order_book": true,
        "order_book_top": 1
    },
    "exchange": {
        "name": "binance",
        "key": "your_exchange_key",
        "secret": "your_exchange_secret",
        "pair_whitelist": ["ETH/USDT", "BTC/USDT", "XRP/USDT"],
        "pair_blacklist": ["BNB/.*"]
    },
    "pairlists": [{"method": "StaticPairList"}],
    "telegram": {
        "enabled": false,
        "token": "your_telegram_token",
        "chat_id": "your_telegram_chat_id"
    },
    "api_server": {
        "enabled": false,
        "listen_ip_address": "127.0.0.1",
        "listen_port": 8080,
        "verbosity": "error",
        "jwt_secret_key": "somethingRandomSomethingRandom123",
        "CORS_origins": [],
        "username": "freqtrader",
        "password": "SuperSecurePassword"
    },
    "bot_name": "freqtrade",
    "initial_state": "running",
    "force_entry_enable": false,
    "internals": {"process_throttle_secs": 5}
}

Essential settings explained

Caution

When you set dry_run: false, your exchange.key and exchange.secret must be valid and the bot will place real orders. Double-check max_open_trades, stake_amount, and your pairlist before going live.

Keeping secrets out of your config

Every config key can be overridden by an environment variable using the prefix FREQTRADE__ and __ to nest. This is the recommended way to handle API keys and tokens:

export FREQTRADE__EXCHANGE__KEY="your_real_key"
export FREQTRADE__EXCHANGE__SECRET="your_real_secret"
export FREQTRADE__TELEGRAM__CHAT_ID="123456789"

Tip

Environment variables take precedence over the file. This keeps secrets out of version control and out of the file you might paste into a support request. To inspect the fully-merged config (with secrets masked) run freqtrade show-config; add --show-sensitive only when you really need to see them.

Multiple config files

You can split configuration across files and combine them. Later files override earlier ones:

freqtrade trade -c config.json -c config-private.json --strategy SampleStrategy

Or list them in add_config_files inside the main config.

5. The Command-Line Interface

Everything starts with the freqtrade command followed by a subcommand:

freqtrade <subcommand> [options]

Running freqtrade with no subcommand prints an error reminding you that a subcommand is required. Use freqtrade --help for the full list and freqtrade <subcommand> --help for a command's options.

Common options (available on most commands)

Strategy options (trading/backtest/hyperopt/plotting)

The full subcommand inventory is in the Command Reference.

6. Everyday Usage

Starting the bot

freqtrade trade --config user_data/config.json --strategy SampleStrategy

The bot enters its main loop: it refreshes the pairlist, downloads the latest candles, runs your strategy to generate entry/exit signals, manages open orders, and then sleeps until the next candle. The loop honors internals.process_throttle_secs (default 5 seconds) as a minimum iteration time and aligns to candle boundaries.

Note

The bot starts in the state given by initial_state (running, paused, or stopped). With running, it begins looking for trades immediately. With paused/stopped, it manages existing trades but won't open new ones until you start it (via Telegram /start or the API).

Forcing dry-run from the command line

Even if your config has dry_run: false, you can force a safe run:

freqtrade trade --config user_data/config.json --strategy SampleStrategy --dry-run

--dry-run removes exchange credentials and simulates trades. This is handy for testing config changes against live prices without risk.

Useful overrides

# Override stake amount and max trades for this run only
freqtrade trade -c config.json -s SampleStrategy --stake-amount 50 --max-open-trades 5

# Use a separate database and notify systemd
freqtrade trade -c config.json -s SampleStrategy --db-url sqlite:///user_data/live.sqlite --sd-notify

Stopping the bot

Press Ctrl+C. Freqtrade catches the interrupt, runs cleanup (optionally cancelling open orders if cancel_open_orders_on_exit is set), and warns you if there are still open trades to manage manually.

Where your data lives

The create-userdir command lays out a user_data/ directory:

user_data/
├── strategies/        your strategy .py files
├── hyperopts/         custom hyperopt loss functions
├── notebooks/         Jupyter analysis notebooks
├── data/              downloaded OHLCV / trades data
├── logs/              log files
├── backtest_results/  backtest output
└── config.json        your configuration (by convention)

7. Writing a Strategy

A strategy is a Python class that subclasses IStrategy. It tells the bot which indicators to compute and when to enter and exit trades. Generate a template with:

freqtrade new-strategy --strategy MyStrategy --template full

The --template choices are minimal, full (default, with sample indicators), and advanced.

The three required pieces

Every strategy must implement three methods and set a few attributes:

from freqtrade.strategy import IStrategy
from pandas import DataFrame
import talib.abstract as ta


class MyStrategy(IStrategy):
    # Tell Freqtrade this strategy targets the current interface
    INTERFACE_VERSION = 3

    # The candle size to trade on
    timeframe = "5m"

    # Take-profit table: minutes-since-entry -> minimum profit ratio
    minimal_roi = {"60": 0.01, "30": 0.02, "0": 0.04}

    # Hard stoploss as a negative ratio (-0.10 = -10%)
    stoploss = -0.10

    def populate_indicators(self, dataframe: DataFrame, metadata: dict) -> DataFrame:
        dataframe["rsi"] = ta.RSI(dataframe)
        return dataframe

    def populate_entry_trend(self, dataframe: DataFrame, metadata: dict) -> DataFrame:
        dataframe.loc[
            (dataframe["rsi"] < 30),
            ["enter_long", "enter_tag"],
        ] = (1, "rsi_oversold")
        return dataframe

    def populate_exit_trend(self, dataframe: DataFrame, metadata: dict) -> DataFrame:
        dataframe.loc[
            (dataframe["rsi"] > 70),
            ["exit_long", "exit_tag"],
        ] = (1, "rsi_overbought")
        return dataframe

Important

Set INTERFACE_VERSION = 3. Version 3 introduced the long/short signal columns (enter_long, exit_long, enter_short, exit_short) and tag columns (enter_tag, exit_tag). If you are migrating an old strategy, run freqtrade strategy-updater to convert it automatically.

Key strategy attributes

Optional callbacks (advanced control)

IStrategy exposes many optional callbacks. Implement only the ones you need:

Tip

Use the @informative decorator (from freqtrade.strategy) to easily pull in higher-timeframe data, and merge_informative_pair to align it onto your base timeframe.

Listing and validating strategies

freqtrade list-strategies --userdir user_data

┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ Strategy name ┃ Location                    ┃ Status ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ MyStrategy    │ user_data/strategies/...    │ OK     │
│ SampleStrategy│ user_data/strategies/...    │ OK     │
└───────────────┴─────────────────────────────┴────────┘

The status column flags LOAD FAILED for strategies with errors and DUPLICATE NAME when two files define the same class name.

8. Downloading Market Data

Backtesting and hyperopt need historical candle (OHLCV) data. Download it with download-data:

freqtrade download-data \
    --config user_data/config.json \
    --pairs ETH/USDT BTC/USDT \
    --timeframes 5m 1h \
    --timerange 20240101-20241231

Warning

--days and --timerange are mutually exclusive — supplying both raises a configuration error. Also, you must provide a list of pairs (via --pairs, --pairs-file, or the config) or the download is refused.

Listing what you have

freqtrade list-data --show-timerange

Found 2 pair / timeframe combinations.
┏━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Pair     ┃ Timeframe ┃ Type ┃ From                ┃ To                  ┃ Candles ┃
┡━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ BTC/USDT │ 5m, 1h    │ spot │ 2024-01-01 00:00:00 │ 2024-12-31 00:00:00 │ ...     │
└──────────┴───────────┴──────┴─────────────────────┴─────────────────────┴─────────┘

Converting data formats

freqtrade convert-data --format-from json --format-to feather --erase
freqtrade trades-to-ohlcv --pairs ETH/USDT --timeframes 5m

9. Backtesting

Backtesting replays historical data through your strategy to estimate how it would have performed.

freqtrade backtesting \
    --config user_data/config.json \
    --strategy MyStrategy \
    --timerange 20240101-20241231 \
    --timeframe 5m

Key backtest options

Tip

Backtest results are cached. If you re-run an identical backtest within the cache age, Freqtrade reuses the prior result instantly. Pass --cache none to force a fresh run.

Reviewing past results

freqtrade backtesting-show --show-pair-list

And to dig into why trades entered/exited:

freqtrade backtesting-analysis --analysis-groups 0 1 2 --enter-reason-list rsi_oversold

The --analysis-groups levels are: 0 simple wins/losses by enter tag, 1 by enter_tag, 2 by enter_tag and exit_tag, 3 by pair and enter_tag, 4 by pair and both tags, 5 by exit_tag.

Checking for bias

Two analysis commands help you trust your results:

# Detect look-ahead bias (using future data accidentally)
freqtrade lookahead-analysis --strategy MyStrategy --timerange 20240101-20240601

# Detect indicators whose values change as more candles arrive
freqtrade recursive-analysis --strategy MyStrategy --startup-candle 199 499 999

Caution

Look-ahead bias makes a strategy look brilliant in backtest and fail in live trading. Always run lookahead-analysis before trusting a profitable backtest.

10. Hyperopt — Optimizing Your Strategy

Hyperopt searches for the best values of parameters you mark as optimizable in your strategy.

freqtrade hyperopt \
    --config user_data/config.json \
    --strategy MyStrategy \
    --hyperopt-loss SharpeHyperOptLoss \
    --spaces buy sell roi stoploss \
    --epochs 200 \
    --timerange 20240101-20240601

Key hyperopt options

Built-in loss functions

Choose with --hyperopt-loss:

ShortTradeDurHyperOptLoss, OnlyProfitHyperOptLoss, SharpeHyperOptLoss, SharpeHyperOptLossDaily, SortinoHyperOptLoss, SortinoHyperOptLossDaily, CalmarHyperOptLoss, MaxDrawDownHyperOptLoss, MaxDrawDownRelativeHyperOptLoss, MaxDrawDownPerPairHyperOptLoss, ProfitDrawDownHyperOptLoss, MultiMetricHyperOptLoss.

List them anytime:

freqtrade list-hyperoptloss

Reviewing hyperopt results

freqtrade hyperopt-list --profitable --min-trades 50
freqtrade hyperopt-show --index 3

Note

Only one Hyperopt can run at a time on a machine — it acquires a file lock. Hyperopt is resource-hungry; run instances sequentially or on separate machines.

Tip

Different loss functions optimize for completely different goals (raw profit vs. risk-adjusted return vs. drawdown). Try a few and compare — the "best" epoch depends entirely on which loss you chose.

11. Controlling the Bot: Telegram

Telegram is the most popular way to monitor and control a running bot. Enable it in your config:

"telegram": {
    "enabled": true,
    "token": "your_telegram_token",
    "chat_id": "your_telegram_chat_id"
}

Get a token from @BotFather and your chat ID by messaging the bot and checking freqtrade's logs, or by using the /tg_info command.

Command groups

Status & information

Trade control

Warning

/forceenter only works when force_entry_enable is true in your config (it defaults to false). Use it deliberately — it bypasses your entry signals.

Tip

Restrict who can command the bot with telegram.authorized_users. Set per-message-type verbosity (on/off/silent) under telegram.notification_settings to cut noise.

12. Controlling the Bot: REST API & FreqUI

Freqtrade ships a FastAPI server (API version 2.48) and a web UI called FreqUI.

Enabling the API

"api_server": {
    "enabled": true,
    "listen_ip_address": "127.0.0.1",
    "listen_port": 8080,
    "username": "freqtrader",
    "password": "SuperSecurePassword",
    "jwt_secret_key": "a-long-random-secret-at-least-32-chars",
    "CORS_origins": []
}

Caution

Keep listen_ip_address at 127.0.0.1 unless you have secured access (reverse proxy + TLS). Exposing the API to 0.0.0.0 puts trade control on the open internet. The jwt_secret_key must be at least 32 characters.

Installing & opening FreqUI

freqtrade install-ui
freqtrade webserver --config user_data/config.json

Then browse to http://127.0.0.1:8080. The webserver subcommand runs the API/UI standalone (for backtesting and analysis through the browser) without trading.

Authentication

# Get a token
curl -X POST -u freqtrader:SuperSecurePassword \
    http://127.0.0.1:8080/api/v1/token/login

Use the returned access_token as a Bearer token; refresh with /api/v1/token/refresh.

Selected endpoints (all under /api/v1)

A live, interactive API reference is available at /docs when api_server.enable_openapi is set.

Webhooks & Discord

Freqtrade can POST events (entries, exits, etc.) to a webhook URL or a Discord channel. Configure under webhook (formats: form, json, raw) or discord (set webhook_url). Messages are templated and can be customized per event type.

13. Pairlists — Choosing What to Trade

A pairlist decides which pairs the bot considers. You configure a chain: the first handler generates the list, subsequent filters refine it.

"pairlists": [
    {"method": "VolumePairList", "number_assets": 20, "sort_key": "quoteVolume", "refresh_period": 1800},
    {"method": "AgeFilter", "min_days_listed": 10},
    {"method": "PriceFilter", "low_price_ratio": 0.01},
    {"method": "SpreadFilter", "max_spread_ratio": 0.005}
]

Available handlers

Generators (use one first): StaticPairList, VolumePairList, PercentChangePairList, ProducerPairList, RemotePairList, MarketCapPairList, CrossMarketPairList.

Filters (chain after a generator): AgeFilter, DelistFilter, FullTradesFilter, OffsetFilter, PairInformationFilter, PerformanceFilter, PrecisionFilter, PriceFilter, RangeStabilityFilter, ShuffleFilter, SpreadFilter, VolatilityFilter.

Test before you trade

freqtrade test-pairlist --config user_data/config.json

Pairs for USDT:
['BTC/USDT', 'ETH/USDT', 'XRP/USDT', ...]

Tip

StaticPairList simply uses your exchange.pair_whitelist. Dynamic lists like VolumePairList change over time; use test-pairlist to preview exactly what they resolve to right now.

14. Protections — Guarding Your Capital

Protections temporarily lock pairs (or all pairs) to stop the bot trading into bad conditions — for example after a string of losses. They are defined in your strategy's protections attribute.

Common protections include stoploss-guard (lock after N stoplosses), max-drawdown protection, low-profit-pairs, and cooldown periods. When a protection triggers, the affected pairs are locked until a computed time, and a notification is sent (if enabled).

Note

Protections are evaluated in live/dry-run automatically. In backtesting they are off by default for speed — add --enable-protections to include them, which produces a more realistic (and usually more conservative) result.

Inspect and manage locks at runtime via Telegram (/locks, /unlock <pair>) or the API (GET/POST/DELETE /api/v1/locks).

15. FreqAI — Machine Learning

FreqAI lets your strategy use machine-learning models (regression, classification, or reinforcement learning) trained on engineered features. It is an optional feature requiring the requirements-freqai.txt (and requirements-freqai-rl.txt for RL/PyTorch) dependencies.

Enabling FreqAI

Add a freqai block to your config (see config_freqai.example.json):

"freqai": {
    "enabled": true,
    "identifier": "unique-id",
    "train_period_days": 15,
    "backtest_period_days": 7,
    "live_retrain_hours": 0,
    "feature_parameters": {
        "include_timeframes": ["3m", "15m", "1h"],
        "include_corr_pairlist": ["BTC/USDT:USDT", "ETH/USDT:USDT"],
        "label_period_candles": 20,
        "include_shifted_candles": 2,
        "indicator_periods_candles": [10, 20]
    },
    "data_split_parameters": {"test_size": 0.33, "random_state": 1},
    "model_training_parameters": {}
}

Then run with a model:

freqtrade trade --config config_freqai.json --strategy FreqaiExampleStrategy --freqaimodel XGBoostRegressor
freqtrade list-freqaimodels

Feature engineering in your strategy

FreqAI strategies implement extra callbacks:

Important

Change the identifier whenever you modify your feature set. FreqAI caches models per identifier; reusing an old identifier after changing features leads to mismatched models. The feature_parameters.include_timeframes and include_corr_pairlist keys are required.

Backtesting FreqAI

freqtrade backtesting --strategy FreqaiExampleStrategy --freqaimodel XGBoostRegressor \
    --timerange 20240101-20240601 --freqai-backtest-live-models

16. Futures & Leverage Trading

Freqtrade supports spot, margin, and futures trading. For futures, set:

"trading_mode": "futures",
"margin_mode": "isolated"

margin_mode is isolated or cross. With futures enabled and a strategy that sets can_short = True, the bot can open short positions (enter_short / exit_short columns). Set per-trade leverage with the leverage callback.

Caution

Futures and leverage dramatically increase risk — positions can be liquidated. Freqtrade tracks a liquidation_price and applies a configurable liquidation_buffer. Test thoroughly in dry-run, and start with low leverage.

Check what a futures-capable exchange offers:

freqtrade list-markets --exchange binance --trading-mode futures
freqtrade list-pairs --exchange binance --trading-mode futures --quote USDT

17. Plotting & Analysis

With the plot dependencies installed:

# Plot candles with your strategy's indicators and trades
freqtrade plot-dataframe --strategy MyStrategy --pairs ETH/USDT \
    --indicators1 sma ema3 --indicators2 macd macdsignal

# Plot cumulative profit
freqtrade plot-profit --strategy MyStrategy --pairs ETH/USDT --auto-open

Output HTML lands in user_data/plot/. For deeper analysis, the bundled Jupyter notebooks under user_data/notebooks/ show how to load and inspect backtest results in pandas.

18. Common Workflows

Develop → test → optimize → deploy

# 1. Create a strategy
freqtrade new-strategy --strategy MyStrategy --template full

# 2. Get data
freqtrade download-data --pairs ETH/USDT BTC/USDT --timeframes 5m --timerange 20240101-

# 3. Backtest
freqtrade backtesting --strategy MyStrategy --timerange 20240101-20240601

# 4. Optimize
freqtrade hyperopt --strategy MyStrategy --hyperopt-loss SharpeHyperOptLoss --epochs 200 \
    --spaces buy sell

# 5. Verify no bias
freqtrade lookahead-analysis --strategy MyStrategy --timerange 20240601-20241201

# 6. Dry-run live
freqtrade trade --strategy MyStrategy --dry-run

# 7. Go live (after weeks of successful dry-run)
freqtrade trade --strategy MyStrategy   # with dry_run:false in config

Run multiple bots

Run separate processes with separate configs and databases:

freqtrade trade -c config-bot1.json -s StratA --db-url sqlite:///user_data/bot1.sqlite
freqtrade trade -c config-bot2.json -s StratB --db-url sqlite:///user_data/bot2.sqlite

Migrate an old strategy

freqtrade strategy-updater --strategy-list MyOldStrategy

This rewrites a pre-v3 strategy to the current interface (adds INTERFACE_VERSION = 3, renames populate_buy_trend→populate_entry_trend, etc.). The original is backed up.

19. Troubleshooting

Error: Freqtrade requires Python version >= 3.11

Cause: You're running an unsupported Python. Solution: Install Python 3.11–3.14 and recreate the virtual environment (./setup.sh -r). Prevention: Use the setup script, which detects a supported interpreter.

Error: Usage of Freqtrade requires a subcommand to be specified.

Cause: You ran freqtrade with no subcommand. Solution: Add a subcommand, e.g. freqtrade trade .... Run freqtrade --help for the list.

Error: --days and --timerange are mutually exclusive.

Cause: You passed both to download-data. Solution: Use only one. --days 30 for a rolling window or --timerange 20240101- for a fixed range.

Error: Downloading data requires a list of pairs.

Cause: No pairs supplied to download-data. Solution: Add --pairs ETH/USDT BTC/USDT, use --pairs-file, or define pair_whitelist in the config.

Error: ...Please ensure that the hyperopt dependencies are installed.

Cause: Hyperopt's optional dependencies are missing. Solution: pip install -r requirements-hyperopt.txt (or choose hyperopt during ./setup.sh).

Error: The Edge module has been deprecated in 2023.9 and removed in 2025.6.

Cause: You ran the removed edge subcommand. Solution: Edge functionality has been removed entirely; there is no replacement subcommand.

Error: Starting balance (...) is smaller than stake_amount ...

Cause: For backtest/hyperopt, your stake_amount exceeds dry_run_wallet * tradable_balance_ratio. Solution: Lower stake_amount, raise dry_run_wallet, or set stake_amount: "unlimited".

Error: --db-url is required for this command.

Cause: show-trades (and some commands) need a database URL. Solution: Add --db-url sqlite:///user_data/tradesv3.sqlite.

Bot warns about open trades on shutdown

Cause: You stopped the bot while trades were open. Solution: Handle them on the exchange, or restart the bot and use /stopentry to wind down gracefully. In dry-run this is only a simulation note.

Another running instance of freqtrade Hyperopt detected.

Cause: A hyperopt is already running (it holds a file lock). Solution: Wait for it to finish or run on a separate machine. Hyperopt cannot run concurrently.

Strategy analysis took longer than 25% of the timeframe

Cause: Your populate_indicators is slow or your pairlist is large. Solution: Reduce indicator work or the number of pairs. This warning means signals/orders may be delayed.

Tip

For database questions (e.g. PostgreSQL connection pool errors) prefer SQLite for single-bot setups; it's the default and needs no server. If you use PostgreSQL, ensure the connection pool is sized for the bot's threads.

20. Frequently Asked Questions

Q: Is Freqtrade free? Yes — it's free and open source.

Q: Will Freqtrade make me money? Freqtrade is a tool, not a strategy. Profitability depends entirely on the strategy you write and the market. The bundled SampleStrategy is a starting point, not a money-maker.

Q: Do I have to use Telegram? No. Telegram, the REST API, and FreqUI are all optional. You can run purely from the command line.

Q: What's the difference between dry-run and live? Dry-run simulates orders against live prices using a virtual wallet (dry_run_wallet); no real orders are placed. Live (dry_run: false) sends real orders with real funds.

Q: How do I keep my API keys safe? Use environment variables with the FREQTRADE__ prefix (e.g. FREQTRADE__EXCHANGE__KEY) instead of putting secrets in the config file.

Q: Which exchanges are supported? Any exchange covered by ccxt, with a curated set validated by Freqtrade. Run freqtrade list-exchanges.

Q: Can I trade futures and go short? Yes — set trading_mode: futures, choose a margin_mode, and write a strategy with can_short = True.

Q: Where are my trades stored? In a SQLite database (tradesv3.sqlite for live, tradesv3.dryrun.sqlite for dry-run) by default. Override with --db-url.

Q: How do I update? ./setup.sh -u for script installs, or docker compose pull && docker compose up -d for Docker.

Q: Can I run more than one strategy at once? Run one bot per strategy, each with its own config and database. A single bot runs a single strategy.

Q: My backtest is very profitable — can I trust it? Not until you run freqtrade lookahead-analysis and freqtrade recursive-analysis to rule out bias, and then dry-run for a meaningful period.

Q: How do I see the config the bot is actually using? freqtrade show-config prints the fully merged configuration with secrets masked.

Q: What does stake_amount: "unlimited" do? It splits your tradable balance evenly across max_open_trades, so each trade uses an equal slice of the wallet.

Q: How do I change the trading pairs without restarting? Edit the config and send /reload_config via Telegram or POST /api/v1/reload_config.

Q: Can I get notified on Discord? Yes — configure the discord block with a webhook_url.

Q: What's FreqAI? An optional machine-learning layer that trains models on engineered features to inform your strategy's signals.

21. Command Reference

Run freqtrade <command> --help for the full option list of any command.

Trading & control

Setup & utilities

Data

Optimization & analysis

Discovery & listing

Plotting