The freqtrade setup path, step by step

The honest shape of a setup

Installing freqtrade is not one step. It is a chain: Python, a virtual environment, the package, a configuration file, exchange credentials, a strategy, and then a first run that tells you which of the previous links is missing. The official quickstart compresses this chain into a few commands; this page keeps the chain visible, because when something breaks — and something always breaks on the first setup — you need to know which link broke.

The three install paths

Path C trades audit time for convenience. The scripts that exist in the community are fine, but "scripted" still means "executed code you have not read". If you use Path C, run the script, then read what it placed on disk — the section on auditing below shows the checklist.

Path A: Python venv, step by step

Step 1 — Python

Check the version you already have. On macOS the system Python is usually too old or mismatched for bot work; most people install a specific version alongside it.

python3 --version   # want 3.10 or newer
which python3

Step 2 — A place for the project

mkdir -p ~/bots/freqtrade && cd ~/bots/freqtrade
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

The prompt now shows (.venv). Everything after this point installs inside that folder, not system-wide. That isolation is the whole point of the venv: you can delete the folder later and your machine is clean.

Step 3 — The package

pip install freqtrade

On Windows the wheel sometimes resolves faster through pip with an upgrade first; on Linux a couple of build dependencies come in through the package manager. The upstream docs carry the exact per-platform list — read that list rather than guessing.

Step 4 — The user directory

freqtrade create-userdir --userdir user_data

This creates the working tree: user_data/strategies/, user_data/data/, user_data/logs/, user_data/notebooks/. Your strategy files and your market data live here.

Step 5 — The configuration

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

An interactive prompt walks through the settings. The next section explains which answers actually matter on first setup and which can be changed later.

Path B: Docker, step by step

Step 1 — Image

docker pull freqtradeorg/freqtrade:stable

Step 2 — A working folder on the host

mkdir -p ~/bots/ft-docker/user_data

Step 3 — A container that keeps its work

docker run --rm -it \
  -v ~/bots/ft-docker/user_data:/freqtrade/user_data \
  freqtradeorg/freqtrade:stable create-userdir --userdir user_data

The -v line mounts the host folder into the container, so strategies and data survive the container. Without a mount you lose everything when the container exits — this is the single most common Docker disappointment in bot setups.

The configuration file

The config answers three questions: where the bot trades, what it trades, and how it behaves while trading. On a first setup only a handful of fields deserve attention.

Exchange API credentials

To trade, the bot needs an API key pair from the exchange, with trading permission and without withdrawal permission. Every major exchange separates these; a key that cannot withdraw is a key whose worst case is a closed position, not an empty account.

• Create the key with trade/read only scope on the exchange site.
• Keep it out of dotfiles that get pushed to public repositories — there is a reason the docs warn about this so loudly.
• Test the pair in dry_run first; a "permission denied" on the first live order is a bad way to learn.

First run and what to expect

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

The first run usually ends in an error, and the error is usually one of three: a missing dependency, a key permission, or a pair that the exchange does not offer in that mode. Each of those is a one-line fix, and each is easier to find if you know the chain from the top of this page — you know which link failed.

Common failure points

• Python version drift. The bot wants 3.10+; the terminal is giving it 3.8. The error message names a syntax feature, which reads strangely until you check versions.
• Timestamp confusion. Candles come in UTC; the chart comes in local time; a strategy that looks off by hours is usually just a timezone read in the wrong direction.
• Docker without a volume mount. A working strategy, gone on restart, because it lived inside the container.
• Pair whitelist against the wrong mode. Futures pairs need the futures pair naming; spot pairs need spot naming. A mixed list fails on the first order.