1.Install Freqtrade

System Requirements

Before we install Freqtrade, we should first make sure the machine is suitable for it. This step looks boring, but it saves time. Most installation problems are not really “Freqtrade problems”. They are usually Python version issues, missing system tools, Docker not being available, or an unsupported operating system environment.

Freqtrade is a Python-based trading bot. That means the runtime environment matters. We are not just downloading a single binary and double-clicking it. We are preparing a small Python application stack that will later connect to exchanges, load strategy files, read configuration, and run command-line tasks.

Operating System Choices

In practice, most people install Freqtrade on Linux, macOS, or Windows. Linux is usually the smoothest option, especially for long-running bot deployments. Ubuntu and Debian-based systems are common choices because package management is straightforward and most examples assume a Unix-like shell.

macOS also works well for learning and local testing. Windows can be used too, especially through PowerShell, WSL, or Docker. The important point is not “which system is best”, but whether your system can provide a stable Python environment and basic developer tools.

If you plan to run the bot continuously, a Linux server or VPS is the most practical setup. If you are only learning and experimenting locally, your personal machine is enough.

Python and Tooling

The real requirement is not just “have Python installed”, but “have a compatible and isolated Python environment”. Freqtrade depends on a specific package ecosystem. If we install it into the system Python together with unrelated projects, package conflicts become much more likely.

A typical local installation environment needs:

python3 --version
pip3 --version
git --version

These three commands check the essentials:

• python3 confirms that Python is available.
• pip3 confirms that Python packages can be installed.
• git is often used to fetch the project source.

The reason this matters is simple. Freqtrade itself is a Python application, its dependencies are installed through pip, and source-based installation generally uses git.

A common beginner mistake is to see python and assume everything is ready. On many systems, python may point to an old version, or not exist at all. It is safer to explicitly use python3.

Hardware Expectations

Freqtrade does not need extreme hardware for basic usage. If you are just learning the CLI, testing a simple strategy, or downloading moderate amounts of historical data, a normal laptop is enough.

Still, different tasks stress different resources. Running the bot itself is light compared with backtesting large datasets or optimization tasks. CPU and memory matter more when you do heavier analysis later. For this chapter, the key point is that installation itself is not demanding. A few gigabytes of free disk space and a stable internet connection are usually enough.

Why Isolation Matters

Since Freqtrade will eventually involve dependencies like pandas, TA libraries, exchange connectors, and strategy code, isolation is not optional in a clean setup. The standard approach is to use either Docker or a Python virtual environment.

That design has a practical benefit: when something breaks, we know where to look. If Freqtrade lives in its own environment, dependency problems are contained. If it shares the environment with unrelated projects, debugging becomes messy very quickly.

Installation Steps

Now we can move from preparation to installation. At a high level, there are two mainstream ways to install Freqtrade:

1. use Docker;
2. install it in a Python virtual environment.

For beginners, Docker is often the easiest way to get a reproducible setup. A virtual environment is also valid and useful, especially if you want to inspect the Python project structure more directly. In this chapter, we will focus on a practical Python-based installation flow, and briefly mention Docker as an alternative.

Creating a Workspace

First, create a dedicated working directory. This is where the project code and related files will live.

mkdir freqtrade
cd freqtrade

This small step is worth doing properly. Later, the bot will generate configuration files, strategy files, logs, and downloaded market data. Keeping everything under one directory makes the project easier to understand and maintain.

Cloning the Project

Next, fetch the Freqtrade source code.

git clone https://github.com/freqtrade/freqtrade.git .

This command downloads the repository into the current directory. The trailing dot means “clone here instead of creating another nested folder”.

What this gives us is not just application code. It also gives us the installation scripts, metadata, and project structure expected by the developers. In Python projects, that structure matters because the installer often relies on files in the repository.

Creating a Virtual Environment

Now create an isolated Python environment.

python3 -m venv .venv
source .venv/bin/activate

On Windows PowerShell, activation is usually:

python -m venv .venv
.venv\Scripts\Activate.ps1

After activation, your shell prompt often changes to show the environment name. That visual cue is useful. It tells you that subsequent python and pip commands are no longer using the global system environment.

This is one of the most important steps in the entire installation. The virtual environment acts like a private Python space. Packages installed here will not pollute other projects, and other projects will not accidentally break this one.

Installing Dependencies and Freqtrade

With the environment activated, install Freqtrade.

pip install --upgrade pip
pip install .

The first command updates pip itself, which reduces the chance of installation issues caused by an old package installer. The second command installs the current project.

Under the hood, pip install . tells Python to install the package defined by the current directory. It reads the project metadata, resolves dependencies, downloads required packages, and makes the freqtrade command available inside the virtual environment.

If you want additional features later, such as optional components, those can be added separately. At the installation stage, our goal is simpler: get the core application working first.

Docker as an Alternative

If you prefer not to manage Python dependencies directly, Docker is the other standard path. In that model, Freqtrade runs inside a container with a predefined environment.

The practical value of Docker is consistency. If Docker works on your machine, the application environment is usually much closer to the expected setup. This is especially helpful when moving from local experiments to server deployment.

Still, Docker introduces its own concepts: images, containers, mounted volumes, and networking. If you are new to command-line tools in general, a Python virtual environment is often easier to understand step by step. We only need one working installation method for now.

Environment Verification

Installation is not complete when the pip install command finishes. It is complete when we can prove the program runs correctly. The goal here is simple: verify that the command exists, the environment is active, and the application responds normally.

Checking the Command

The first verification step is to ask Freqtrade for its version.

freqtrade --version

If everything is set up correctly, you should see version information printed in the terminal.

This command is more important than it looks. It tests several things at once:

• the virtual environment is active;
• the freqtrade executable is available in that environment;
• Python can start the application;
• the installation did not fail halfway through.

If the shell says “command not found”, the problem is usually not the package itself, but one of two things: the virtual environment was never activated, or the installation did not complete successfully.

Checking the Help Output

Next, ask for the built-in help.

freqtrade --help

This confirms that the command-line interface is alive and able to list its subcommands. We are not learning the CLI in detail yet, but this is a good functional check.

The help output tells us something useful from an engineering perspective: Freqtrade is designed as a command-line application with many operational modes. That is why installation is only the first step. Once the CLI works, the rest of the learning process becomes much smoother.

Creating an Initial User Directory

A practical verification step is to let Freqtrade create its working structure.

freqtrade create-userdir --userdir user_data

This generates a user_data directory for your project files. You can then inspect it:

ls user_data

On Windows PowerShell:

Get-ChildItem user_data

This step matters because it verifies that Freqtrade can do actual filesystem work, not just print a version string. It is also the first time you see the project’s expected layout for user-managed data.

The idea behind this design is clean separation. The application code stays in the installed package, while your strategies, configs, and runtime files live in a user directory. That separation makes updates safer and day-to-day work more organized.

Generating a Starter Configuration

If you want one more confidence check, generate a sample configuration.

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

This command creates a config file interactively or semi-interactively depending on the environment. The important thing for this chapter is not the content of the config itself. It is that the application can initialize a real working project.

At this point, your environment is no longer just “installed”. It is operational.

Common Issues

Even with a careful setup, some friction is normal. The useful approach is to connect each symptom to the underlying cause instead of trying random fixes.

Command Not Found

A very common problem is:

freqtrade: command not found

In most cases, this means the virtual environment is not active. Go back and activate it again:

source .venv/bin/activate

Or on Windows PowerShell:

.venv\Scripts\Activate.ps1

If activation is already correct, then the installation may have failed earlier. Running the install command again inside the active environment is usually the next reasonable step.

The key insight is that the freqtrade command is not normally installed globally. It belongs to the environment where you installed it. So the shell must be pointed at that environment.

Wrong Python Version

Another common issue is a Python version mismatch. You may see dependency resolution errors or installation failures that look unrelated at first glance.

That is why we checked the Python version before installation. If python3 --version shows an unsupported or unexpected version, the fix is usually to install the correct Python version first, then recreate the virtual environment.

Do not try to “repair” an environment built on the wrong Python foundation. It is usually faster and cleaner to remove .venv and create a new one.

rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install .

This works because virtual environments are disposable by design. Rebuilding them is not a failure; it is normal maintenance.

Build Dependency Errors

Sometimes installation fails because system-level build tools or libraries are missing. This is more likely on fresh Linux systems.

If a package compilation error appears, the real issue is often not Freqtrade itself, but a missing compiler toolchain or development library required by one of its Python dependencies.

In that situation, the pragmatic fix is to install the missing system packages using your OS package manager, then retry the installation. The exact package names vary by distribution, so the main lesson is diagnostic: read the first meaningful error line, not just the final “installation failed” message.

Windows Script Policy Problems

On Windows PowerShell, activating the virtual environment may fail because script execution is restricted.

The symptom may look like PowerShell refusing to run Activate.ps1. In that case, the issue is not with Freqtrade. It is PowerShell’s execution policy.

A common practical workaround is to open PowerShell with appropriate permissions and allow script execution for the current user, then activate the environment again. The important point is conceptual: if activation fails before installation even starts, focus on the shell environment first.

Mixed Environments

One subtle issue appears when users switch between terminals and forget which environment is active. They install packages in one shell, then run commands in another shell where the environment is inactive.

This creates confusing behavior: installation appears successful, but the command is missing. The solution is discipline. After opening a new terminal, activate the environment first, then work from there.

That small habit prevents many “it worked a minute ago” moments.

Summary

At this stage, we have done the essential setup work: checked that the system can support Freqtrade, created a clean workspace, installed it in an isolated environment, and verified that the command actually runs.

The practical outcome is more important than the individual commands. You now have a working Freqtrade environment that is separated from the rest of your machine, easier to maintain, and ready for the next step. If something went wrong, the pattern is usually clear: check Python, check the virtual environment, then check whether the command is available inside that environment.

Installation is only the foundation, though. Once the tool is running, the next useful skill is learning how to talk to it efficiently. In the next chapter, we will get familiar with the Freqtrade CLI itself: how commands are structured, how to discover available options, and how to work with the tool comfortably from the terminal.