## Clone repo
git clone https://github.com/freqtrade/freqtrade.git
cd freqtrade
## Create and activate virtual env
python3 -m venv .env
source .env/bin/activate
## Install dependencies
pip install -r requirements.txt
## Optional: install docker-compose for containerized use
sudo apt install docker-compose
You can verify the install with:
freqtrade --version
Expect something like "Freqtrade 2023.8.0" depending on the release.
Important: I’ve seen issues where missing system libraries (like libffi or libssl) cause install errors. Installing build-essential and libssl-dev on Ubuntu usually solves those.
Building Your First Custom Strategy in Python
Freqtrade’s strategy system is Python-based and uses pandas DataFrames for data manipulation. This means you get flexibility to add any indicators or machine learning signals.
Here’s a minimal custom strategy example to illustrate:
from freqtrade.strategy.interface import IStrategy
import talib
class SimpleSmaCrossStrategy(IStrategy):
## Minimal timeframe
timeframe = '5m'
def populate_indicators(self, dataframe, metadata):
dataframe['sma50'] = talib.SMA(dataframe['close'], timeperiod=50)
dataframe['sma200'] = talib.SMA(dataframe['close'], timeperiod=200)
return dataframe
def populate_buy_trend(self, dataframe, metadata):
dataframe.loc[(dataframe['sma50'] > dataframe['sma200']), 'buy'] = 1
return dataframe
def populate_sell_trend(self, dataframe, metadata):
dataframe.loc[(dataframe['sma50'] < dataframe['sma200']), 'sell'] = 1
return dataframe
The key methods are populate_indicators (calculate TA), populate_buy_trend, and populate_sell_trend for entry/exit signals.
You can expand this by adding indicators from TA-Lib, or custom features (more on feature engineering below).
More complex strategy templates and examples are available on the repo’s strategies folder.
Backtesting and Avoiding Look-Ahead Bias
Backtesting is a must before risking real funds. Freqtrade’s backtesting command:
freqtrade backtesting --strategy SimpleSmaCrossStrategy
But beware: look-ahead bias can inflate results if your strategy uses future data accidentally (like referencing close at t+1 during indicator calculation).
What I've found helps is strict use of .shift() in pandas to lag your signal columns correctly. Also, keep the timeframes consistent and only use data available at decision time.
Example (pseudo-code):
## incorrect - future price leakage
buy_signal = dataframe['close'].shift(-1) > dataframe['close']
## correct - use current or past data only
buy_signal = dataframe['close'] > dataframe['close'].shift(1)
Freqtrade doesn't block this by default, so developer discipline is key.
Document your assumptions in the strategy source — I often comment when I introduce any lags or leads.
Dry Run and Live Trading Workflow
Freqtrade supports a dry-run mode that mimics live trading without spending real cash. It’s an invaluable safety net I always use before going live.
Start dry-run with:
freqtrade trade --strategy SimpleSmaCrossStrategy --dry-run
No exchange orders are placed; it records paper trades and simulates balances.
When ready, switch to live (real orders) by removing --dry-run, but: double-check your API keys don’t have withdrawal permissions — a basic but often overlooked security step.
In production I switched to using session keys and setting max order amounts to limit damage surface.
Freqtrade Hyperopt for Parameter Optimization
Freqtrade includes a hyper-optimization tool called hyperopt; it helps tune your strategy parameters across historical data.
Run hyperopt with:
freqtrade hyperopt --strategy SimpleSmaCrossStrategy --hyperopt-loss SharpeHyperOptLoss
It cycles through parameter combinations defined in your strategy’s hyperparameters dict.
Beware though — this consumes CPU heavily and risks overfitting if your dataset is narrow or artifact-prone.
Try to keep validation periods separate from training, and consider restrictions to avoid unrealistic gains (e.g., ignore impossible fills).
Integrating FreqAI for Machine Learning Strategies
Freqtrade recently added the FreqAI module to integrate ML models like LightGBM and random forest regressors.
To set up a LightGBM regressor example:
- Prepare features via FreqAI feature engineering (indicators + custom metrics).
- Train an LGBM model on historical data.
- Plug model into Freqtrade strategy predict method.
Here’s a simplified snippet:
from freqai.models import LightGBMRegressor
class FreqAIBasedStrategy(IStrategy):
timeframe = '15m'
def __init__(self):
self.model = LightGBMRegressor.load('path/to/model.pkl')
def populate_indicators(self, dataframe, metadata):
## add features e.g. MACD, RSI
return dataframe
def populate_buy_trend(self, dataframe, metadata):
dataframe['prediction'] = self.model.predict(dataframe.dropna())
dataframe.loc[(dataframe['prediction'] > 0.5), 'buy'] = 1
return dataframe
This ML integration helps detect nonlinear patterns beyond classical indicators.
For a full guide, see the internal freqai-ml-integrations page.
Telegram Webhook Alerts Integration
Freqtrade supports alerting via Telegram webhooks to notify on trades, errors, or strategy signals.
Steps to integrate:
- Create a Telegram bot via BotFather and get the API token.
- Get your chat ID from the Telegram API.
- Configure
config.json with webhook settings:
{
"telegram": {
"enabled": true,
"token": "your-bot-token",
"chat_id": "your-chat-id"
}
}
- Run bot, and alerts like buy/sell events will post to your Telegram.
This is hands-down the easiest way to stay updated without polling logs.
Troubleshooting and Common Gotchas
Running Freqtrade smoothly involves some troubleshooting. Here are what I hit often:
Installing TA-Lib: The pip wheel often fails; installing system libta-lib-dev then reinstalling helps.
Docker build cache issues: Clear with docker system prune if builds fail unpredictably.
Backtesting errors: Make sure your strategy methods return modified dataframes and set flags properly — missing 'buy' or 'sell' columns causes silent fails.
Exchange API rate limits: CCXT integration can hit limits; using --enable-rate-limit and setting proper timeouts is smart.
Unlimited approvals: If your live strategy handles ERC-20 tokens, don’t use unlimited allowance approvals for security.
More troubleshooting tips are in the trading-bot-troubleshooting guide.
Conclusion and Next Steps
Freqtrade is a flexible, open-source bot that balances ease of use with customizability, especially for Python-savvy developers. The learning curve is real, but methodical setup lets you experiment in safe dry-run mode before risking funds.
Start by setting up your environment and cloning the repo, then build a simple strategy and backtest it extensively. Once you’re comfortable, integrate FreqAI for ML-enhanced signals, and optimize parameters with hyperopt.
Don’t skip integrating Telegram alerts — they make live monitoring manageable.
For ongoing learning, check the detailed freqai-ml-integrations and ccxt-python-integration tutorials next. If market making interests you, the hummingbot-market-making guide offers a complementary perspective.
Feel free to explore the comparison of trading bot frameworks in trading-bot-frameworks-comparison to see where Freqtrade fits.
Happy coding and trading — remember that edge comes from careful testing, constant refinement, and solid risk control!
| Feature |
Freqtrade |
Alternative Bots |
| Language |
Python |
Python, Rust, JS |
| Strategy customization |
Full Python support |
Mixed |
| ML integration |
Via FreqAI module |
Limited |
| Backtesting |
Built-in with metrics |
Varies |
| Hyperparameter tuning |
Hyperopt included |
Sometimes manual |
| Supported exchanges |
15+ via CCXT |
Depends |
| License |
MIT |
Mostly open-source |
Explore next:
Related: Backtesting LLM Trading Agents Without Look
