Writing a requirements.txt for a Python bot

What the file is

A plain text file with one package per line, which pip installs in one go with pip install -r requirements.txt. Lines starting with # are comments. It is not a Python file and nothing in it runs; it is a list.

Each line is the name the package is published under on PyPI, optionally followed by which versions are acceptable.

# The Discord library
discord.py~=2.4

# Loads the token from .env on your own machine
python-dotenv

List what you import

The quickest way to write the file is to go through your imports and add a line for each one that is not part of Python itself. You only need the packages your code imports directly: pip works out what they depend on and installs that too.

pip freeze looks like a shortcut and often is not. It lists everything installed in the current environment, so run outside a virtual environment it includes every package you ever installed for any project, pinned to exact versions, sometimes including packages that only exist for Windows, such as pywin32, and will not install on a Linux server.

If you want to use pip freeze, give the bot its own virtual environment first, install only what it needs there, and freeze that.

python -m venv .venv

# Windows: .venv\Scripts\activate
# macOS and Linux:
source .venv/bin/activate

pip install discord.py python-dotenv
pip freeze > requirements.txt

Import names are not package names

The name you import and the name you install are often different, and requirements.txt needs the second. A line that uses the import name either fails with "No matching distribution found" or, worse, installs an unrelated package that happens to have that name.

import discord     ->  discord.py
import dotenv      ->  python-dotenv
import yaml        ->  PyYAML
import PIL         ->  Pillow
import bs4         ->  beautifulsoup4

One Discord library at a time

discord.py and Pycord (published as py-cord) both install a module called discord. List both and one overwrites the other's files, which shows up as confusing errors about attributes that should exist. Pick one, and make sure only that one is in the file.

The same goes for older tutorials that installed a library under one name and a fork of it under another. If your imports say discord, exactly one line in requirements.txt should provide it.

Pin enough, not everything

An unpinned line installs whatever is newest on the day, so a deploy next month can bring a major version that changes how your code has to be written. An exact pin with == stops that, but also stops bug fixes, and exact pins copied from another machine can name a version that does not exist for the Python version the host runs.

The middle ground is the compatible-release operator. discord.py~=2.4 means version 2.4 or anything newer within 2.x, which takes fixes and features but never 3.0. Use it for the libraries your code is written against, and leave small helpers unpinned.

Check it before you deploy

The reliable test is to install the file into an empty environment and start the bot from there. If anything is missing from the list, it fails on your machine rather than on the server.

python -m venv /tmp/check
/tmp/check/bin/pip install -r requirements.txt
/tmp/check/bin/python main.py

On our hosting

Your requirements.txt is installed on deploy, before the bot starts, so there is nothing to install by hand. Upload your code and the file, and leave any virtual environment folder behind: it belongs to your machine and is installed afresh on the server.

If the console shows a ModuleNotFoundError, the package is not in requirements.txt, or it is there under the wrong name. Add the line, and the next start installs it.