stable/docs/installation.md

436 lines
14 KiB
Markdown
Raw Normal View History

2018-01-13 02:36:12 +00:00
# Installation
2019-05-25 14:13:18 +00:00
2018-01-09 04:27:41 +00:00
This page explains how to prepare your environment for running the bot.
2018-01-13 02:36:12 +00:00
The freqtrade documentation describes various ways to install freqtrade
* [Docker images](docker_quickstart.md) (separate page)
* [Script Installation](#script-installation)
2021-01-27 13:23:53 +00:00
* [Manual Installation](#manual-installation)
* [Installation with Conda](#installation-with-conda)
2019-05-25 14:13:18 +00:00
Please consider using the prebuilt [docker images](docker_quickstart.md) to get started quickly while evaluating how freqtrade works.
2021-01-27 13:04:04 +00:00
2021-01-25 20:41:55 +00:00
------
## Information
2021-01-25 20:41:55 +00:00
For Windows installation, please use the [windows installation guide](windows_installation.md).
2021-01-28 23:09:39 +00:00
The easiest way to install and run Freqtrade is to clone the bot Github repository and then run the `./setup.sh` script, if it's available for your platform.
!!! Note "Version considerations"
2021-01-25 20:41:55 +00:00
When cloning the repository the default working branch has the name `develop`. This branch contains all last features (can be considered as relatively stable, thanks to automated tests).
The `stable` branch contains the code of the last release (done usually once per month on an approximately one week old snapshot of the `develop` branch to prevent packaging bugs, so potentially it's more stable).
!!! Note
2021-01-04 08:40:17 +00:00
Python3.7 or higher and the corresponding `pip` are assumed to be available. The install-script will warn you and stop if that's not the case. `git` is also needed to clone the Freqtrade repository.
Also, python headers (`python<yourversion>-dev` / `python<yourversion>-devel`) must be available for the installation to complete successfully.
2021-01-25 21:18:38 +00:00
!!! Warning "Up-to-date clock"
The clock on the system running the bot must be accurate, synchronized to a NTP server frequently enough to avoid problems with communication to the exchanges.
2018-01-13 02:36:12 +00:00
------
## Requirements
2021-01-25 20:41:55 +00:00
These requirements apply to both [Script Installation](#script-installation) and [Manual Installation](#manual-installation).
2021-01-25 21:18:38 +00:00
2021-12-05 08:26:44 +00:00
!!! Note "ARM64 systems"
If you are running an ARM64 system (like a MacOS M1 or an Oracle VM), please use [docker](docker_quickstart.md) to run freqtrade.
2021-12-05 08:26:44 +00:00
While native installation is possible with some manual effort, this is not supported at the moment.
### Install guide
2021-01-25 21:18:38 +00:00
* [Python >= 3.7.x](http://docs.python-guide.org/en/latest/starting/installation/)
* [pip](https://pip.pypa.io/en/stable/installing/)
* [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [virtualenv](https://virtualenv.pypa.io/en/stable/installation.html) (Recommended)
* [TA-Lib](https://mrjbq7.github.io/ta-lib/install.html) (install instructions [below](#install-ta-lib))
2021-01-25 21:18:38 +00:00
### Install code
2018-01-13 02:36:12 +00:00
2020-11-30 19:56:14 +00:00
We've included/collected install instructions for Ubuntu, MacOS, and Windows. These are guidelines and your success may vary with other distros.
2018-12-31 10:04:22 +00:00
OS Specific steps are listed first, the [Common](#common) section below is necessary for all systems.
2018-01-13 02:36:12 +00:00
2019-06-27 17:51:04 +00:00
!!! Note
2020-12-14 18:18:54 +00:00
Python3.7 or higher and the corresponding pip are assumed to be available.
2018-01-02 02:17:10 +00:00
2021-01-25 20:41:55 +00:00
=== "Debian/Ubuntu"
#### Install necessary dependencies
2018-01-13 02:36:12 +00:00
```bash
2021-01-25 21:12:48 +00:00
# update repository
sudo apt-get update
2021-01-25 21:12:48 +00:00
# install packages
2021-11-17 18:36:38 +00:00
sudo apt install -y python3-pip python3-venv python3-dev python3-pandas git curl
```
2018-01-13 02:36:12 +00:00
=== "RaspberryPi/Raspbian"
2020-11-30 16:37:19 +00:00
The following assumes the latest [Raspbian Buster lite image](https://www.raspberrypi.org/downloads/raspbian/).
This image comes with python3.7 preinstalled, making it easy to get freqtrade up and running.
2018-01-02 02:17:10 +00:00
Tested using a Raspberry Pi 3 with the Raspbian Buster lite image, all updates applied.
2021-01-15 00:14:11 +00:00
```bash
2021-11-17 18:36:38 +00:00
sudo apt-get install python3-venv libatlas-base-dev cmake curl
2020-11-30 16:37:19 +00:00
# Use pywheels.org to speed up installation
sudo echo "[global]\nextra-index-url=https://www.piwheels.org/simple" > tee /etc/pip.conf
2020-11-30 16:37:19 +00:00
git clone https://github.com/freqtrade/freqtrade.git
cd freqtrade
bash setup.sh -i
```
!!! Note "Installation duration"
Depending on your internet speed and the Raspberry Pi version, installation can take multiple hours to complete.
Due to this, we recommend to use the pre-build docker-image for Raspberry, by following the [Docker quickstart documentation](docker_quickstart.md)
!!! Note
The above does not install hyperopt dependencies. To install these, please use `python3 -m pip install -e .[hyperopt]`.
We do not advise to run hyperopt on a Raspberry Pi, since this is a very resource-heavy operation, which should be done on powerful machine.
2021-01-28 23:09:39 +00:00
------
## Freqtrade repository
2021-01-28 23:09:39 +00:00
Freqtrade is an open source crypto-currency trading bot, whose code is hosted on `github.com`
2021-01-28 23:09:39 +00:00
```bash
# Download `develop` branch of freqtrade repository
git clone https://github.com/freqtrade/freqtrade.git
# Enter downloaded directory
cd freqtrade
# your choice (1): novice user
2021-01-28 23:09:39 +00:00
git checkout stable
# your choice (2): advanced user
2021-01-28 23:09:39 +00:00
git checkout develop
```
(1) This command switches the cloned repository to the use of the `stable` branch. It's not needed, if you wish to stay on the (2) `develop` branch.
You may later switch between branches at any time with the `git checkout stable`/`git checkout develop` commands.
??? Note "Install from pypi"
An alternative way to install Freqtrade is from [pypi](https://pypi.org/project/freqtrade/). The downside is that this method requires ta-lib to be correctly installed beforehand, and is therefore currently not the recommended way to install Freqtrade.
``` bash
pip install freqtrade
```
2021-01-28 23:09:39 +00:00
------
## Script Installation
First of the ways to install Freqtrade, is to use provided the Linux/MacOS `./setup.sh` script, which install all dependencies and help you configure the bot.
Make sure you fulfill the [Requirements](#requirements) and have downloaded the [Freqtrade repository](#freqtrade-repository).
2021-01-28 23:09:39 +00:00
### Use /setup.sh -install (Linux/MacOS)
2021-01-28 23:09:39 +00:00
If you are on Debian, Ubuntu or MacOS, freqtrade provides the script to install freqtrade.
2021-01-28 23:09:39 +00:00
```bash
# --install, Install freqtrade from scratch
./setup.sh -i
```
### Activate your virtual environment
Each time you open a new terminal, you must run `source .env/bin/activate` to activate your virtual environment.
2021-01-28 23:09:39 +00:00
```bash
# then activate your .env
source ./.env/bin/activate
```
### Congratulations
2021-01-28 23:09:39 +00:00
[You are ready](#you-are-ready), and run the bot
### Other options of /setup.sh script
2021-01-28 23:09:39 +00:00
You can as well update, configure and reset the codebase of your bot with `./script.sh`
2021-01-28 23:09:39 +00:00
```bash
# --update, Command git pull to update.
./setup.sh -u
# --reset, Hard reset your develop/stable branch.
./setup.sh -r
```
```
** --install **
2021-01-28 23:09:39 +00:00
With this option, the script will install the bot and most dependencies:
You will need to have git and python3.7+ installed beforehand for this to work.
2021-01-28 23:09:39 +00:00
* Mandatory software as: `ta-lib`
* Setup your virtualenv under `.env/`
2021-01-28 23:09:39 +00:00
This option is a combination of installation tasks and `--reset`
2021-01-28 23:09:39 +00:00
** --update **
2021-01-28 23:09:39 +00:00
This option will pull the last version of your current branch and update your virtualenv. Run the script with this option periodically to update your bot.
2021-01-28 23:09:39 +00:00
** --reset **
2021-01-28 23:09:39 +00:00
This option will hard reset your branch (only if you are on either `stable` or `develop`) and recreate your virtualenv.
```
2021-01-28 23:09:39 +00:00
-----
## Manual Installation
Make sure you fulfill the [Requirements](#requirements) and have downloaded the [Freqtrade repository](#freqtrade-repository).
2021-01-28 23:09:39 +00:00
### Install TA-Lib
2018-01-13 02:36:12 +00:00
#### TA-Lib script installation
2020-02-01 13:06:31 +00:00
```bash
sudo ./build_helpers/install_ta-lib.sh
```
!!! Note
This will use the ta-lib tar.gz included in this repository.
##### TA-Lib manual installation
2018-01-02 02:17:10 +00:00
Official webpage: https://mrjbq7.github.io/ta-lib/install.html
2018-01-13 02:36:12 +00:00
```bash
2021-01-27 13:04:04 +00:00
wget http://prdownloads.sourceforge.net/ta-lib/ta-lib-0.4.0-src.tar.gz
tar xvzf ta-lib-0.4.0-src.tar.gz
2018-01-02 02:17:10 +00:00
cd ta-lib
sed -i.bak "s|0.00000001|0.000000000000000001 |g" src/ta_func/ta_utility.h
./configure --prefix=/usr/local
2018-01-02 02:17:10 +00:00
make
sudo make install
2021-06-28 17:44:15 +00:00
# On debian based systems (debian, ubuntu, ...) - updating ldconfig might be necessary.
sudo ldconfig
2018-01-02 02:17:10 +00:00
cd ..
rm -rf ./ta-lib*
```
2021-01-25 21:12:48 +00:00
#### Setup Python virtual environment (virtualenv)
You will run freqtrade in separated `virtual environment`
```bash
# create virtualenv in directory /freqtrade/.env
python3 -m venv .env
# run virtualenv
source .env/bin/activate
2018-01-02 02:17:10 +00:00
```
2021-01-25 20:41:55 +00:00
#### Install python dependencies
2018-01-13 02:36:12 +00:00
2021-01-15 00:14:11 +00:00
```bash
python3 -m pip install --upgrade pip
python3 -m pip install -e .
2018-01-13 02:36:12 +00:00
```
### Congratulations
2021-01-25 21:12:48 +00:00
2021-01-28 23:09:39 +00:00
[You are ready](#you-are-ready), and run the bot
2018-08-26 18:09:12 +00:00
2021-01-25 20:41:55 +00:00
#### (Optional) Post-installation Tasks
2018-08-26 18:09:12 +00:00
!!! Note
If you run the bot on a server, you should consider using [Docker](docker_quickstart.md) or a terminal multiplexer like `screen` or [`tmux`](https://en.wikipedia.org/wiki/Tmux) to avoid that the bot is stopped on logout.
2021-01-25 21:12:48 +00:00
On Linux with software suite `systemd`, as an optional post-installation task, you may wish to setup the bot to run as a `systemd service` or configure it to send the log messages to the `syslog`/`rsyslog` or `journald` daemons. See [Advanced Logging](advanced-setup.md#advanced-logging) for details.
------
2021-01-27 13:25:16 +00:00
## Installation with Conda
2019-08-05 17:25:43 +00:00
2021-01-27 13:23:53 +00:00
Freqtrade can also be installed with Miniconda or Anaconda. We recommend using Miniconda as it's installation footprint is smaller. Conda will automatically prepare and manage the extensive library-dependencies of the Freqtrade program.
2019-08-05 17:25:43 +00:00
### What is Conda?
2021-01-15 00:14:11 +00:00
Conda is a package, dependency and environment manager for multiple programming languages: [conda docs](https://docs.conda.io/projects/conda/en/latest/index.html)
2021-01-15 00:14:11 +00:00
### Installation with conda
2021-01-15 00:14:11 +00:00
2021-01-27 13:04:04 +00:00
#### Install Conda
2021-01-15 00:14:11 +00:00
2021-01-25 20:41:55 +00:00
[Installing on linux](https://conda.io/projects/conda/en/latest/user-guide/install/linux.html#install-linux-silent)
2021-01-25 19:51:01 +00:00
2021-01-25 20:41:55 +00:00
[Installing on windows](https://conda.io/projects/conda/en/latest/user-guide/install/windows.html)
2021-01-15 00:14:11 +00:00
2021-01-25 20:41:55 +00:00
Answer all questions. After installation, it is mandatory to turn your terminal OFF and ON again.
2021-01-15 00:14:11 +00:00
2021-01-25 20:41:55 +00:00
#### Freqtrade download
2021-01-15 00:14:11 +00:00
2021-01-24 17:03:56 +00:00
Download and install freqtrade.
2021-01-15 00:14:11 +00:00
2021-01-16 22:24:22 +00:00
```bash
2021-01-24 17:03:56 +00:00
# download freqtrade
git clone https://github.com/freqtrade/freqtrade.git
# enter downloaded directory 'freqtrade'
cd freqtrade
2018-08-28 17:30:26 +00:00
```
2021-05-15 13:21:21 +00:00
#### Freqtrade install: Conda Environment
2021-01-24 17:03:56 +00:00
2021-01-25 20:41:55 +00:00
Prepare conda-freqtrade environment, using file `environment.yml`, which exist in main freqtrade directory
2021-01-25 19:51:01 +00:00
```bash
conda env create -n freqtrade-conda -f environment.yml
```
2021-01-24 17:03:56 +00:00
!!! Note "Creating Conda Environment"
The conda command `create -n` automatically installs all nested dependencies for the selected libraries, general structure of installation command is:
```bash
# choose your own packages
conda env create -n [name of the environment] [python version] [packages]
# point to file with packages
conda env create -n [name of the environment] -f [file]
```
#### Enter/exit freqtrade-conda environment
2021-01-15 00:14:11 +00:00
2021-01-25 19:51:01 +00:00
To check available environments, type
2021-01-15 00:14:11 +00:00
```bash
2021-01-25 19:51:01 +00:00
conda env list
2021-01-15 00:14:11 +00:00
```
2021-01-25 19:51:01 +00:00
Enter installed environment
2021-01-15 00:14:11 +00:00
```bash
2021-01-25 19:51:01 +00:00
# enter conda environment
2021-01-25 20:41:55 +00:00
conda activate freqtrade-conda
2021-01-25 19:51:01 +00:00
# exit conda environment - don't do it now
2021-01-25 19:51:01 +00:00
conda deactivate
2021-01-27 13:23:53 +00:00
```
2021-01-24 21:31:36 +00:00
2021-01-25 19:51:01 +00:00
Install last python dependencies with pip
2021-01-24 21:31:36 +00:00
```bash
python3 -m pip install --upgrade pip
python3 -m pip install -e .
2021-01-15 00:14:11 +00:00
```
### Congratulations
2021-01-15 00:14:11 +00:00
2021-01-28 23:09:39 +00:00
[You are ready](#you-are-ready), and run the bot
2021-01-15 00:14:11 +00:00
2021-01-28 23:09:39 +00:00
### Important shortcuts
2021-01-15 00:14:11 +00:00
```bash
2021-01-24 17:03:56 +00:00
# list installed conda environments
conda env list
2021-01-15 00:14:11 +00:00
# activate base environment
conda activate
# activate freqtrade-conda environment
conda activate freqtrade-conda
#deactivate any conda environments
2021-01-24 17:03:56 +00:00
conda deactivate
2021-01-15 00:14:11 +00:00
```
### Further info on anaconda
2021-01-27 13:04:04 +00:00
!!! Info "New heavy packages"
It may happen that creating a new Conda environment, populated with selected packages at the moment of creation takes less time than installing a large, heavy library or application, into previously set environment.
2021-01-27 13:04:04 +00:00
!!! Warning "pip install within conda"
The documentation of conda says that pip should NOT be used within conda, because internal problems can occur.
However, they are rare. [Anaconda Blogpost](https://www.anaconda.com/blog/using-pip-in-a-conda-environment)
2021-01-27 13:04:04 +00:00
Nevertheless, that is why, the `conda-forge` channel is preferred:
2021-01-27 13:04:04 +00:00
* more libraries are available (less need for `pip`)
* `conda-forge` works better with `pip`
* the libraries are newer
2021-01-15 00:14:11 +00:00
Happy trading!
2021-01-28 23:09:39 +00:00
-----
## You are ready
You've made it this far, so you have successfully installed freqtrade.
2021-01-28 23:09:39 +00:00
### Initialize the configuration
2021-01-28 23:09:39 +00:00
```bash
# Step 1 - Initialize user folder
freqtrade create-userdir --userdir user_data
# Step 2 - Create a new configuration file
freqtrade new-config --config config.json
```
You are ready to run, read [Bot Configuration](configuration.md), remember to start with `dry_run: True` and verify that everything is working.
2021-01-28 23:09:39 +00:00
To learn how to setup your configuration, please refer to the [Bot Configuration](configuration.md) documentation page.
2021-01-28 23:09:39 +00:00
### Start the Bot
2021-01-28 23:09:39 +00:00
```bash
freqtrade trade --config config.json --strategy SampleStrategy
2021-01-28 23:09:39 +00:00
```
!!! Warning
You should read through the rest of the documentation, backtest the strategy you're going to use, and use dry-run before enabling trading with real money.
-----
## Troubleshooting
### Common problem: "command not found"
2021-01-28 23:09:39 +00:00
If you used (1)`Script` or (2)`Manual` installation, you need to run the bot in virtual environment. If you get error as below, make sure venv is active.
```bash
# if:
bash: freqtrade: command not found
# then activate your .env
source ./.env/bin/activate
```
2021-01-15 00:14:11 +00:00
2020-01-02 13:52:34 +00:00
### MacOS installation error
Newer versions of MacOS may have installation failed with errors like `error: command 'g++' failed with exit status 1`.
2020-01-02 13:52:34 +00:00
This error will require explicit installation of the SDK Headers, which are not installed by default in this version of MacOS.
2020-01-02 13:52:34 +00:00
For MacOS 10.14, this can be accomplished with the below command.
2021-01-15 00:14:11 +00:00
```bash
2020-01-02 13:52:34 +00:00
open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg
```
2020-09-04 05:12:08 +00:00
If this file is inexistent, then you're probably on a different version of MacOS, so you may need to consult the internet for specific resolution details.
### MacOS installation error with python 3.9
When using python 3.9 on macOS, it's currently necessary to install some os-level modules to allow dependencies to compile.
The errors you'll see happen during installation and are related to the installation of `tables` or `blosc`.
You can install the necessary libraries with the following command:
2021-01-15 00:14:11 +00:00
```bash
brew install hdf5 c-blosc
```
After this, please run the installation (script) again.