A Clean Python Project Others Can Run
20 min · Beginner
Need help? Ask a tutor on WhatsApp (opens in a new tab)Showing steps for Windows. They are marked “On Windows” below.
A project is only useful to others if they can run it. Three small files do most of the work: .gitignore keeps junk out, requirements.txt lists the packages, and the README gives the steps.
A tidy project layout
Keep the files that people need at the top, and your code in one clear place. Every file should have a reason to be there.
grade-tools/ README.md requirements.txt .gitignore .env.example main.py grades/ __init__.py report.py tests/ test_report.py.env.example shows which settings the program needs, with fake values. The real .env file stays on your computer.
Keep generated files and secrets out
Python creates folders you should never share, such as the virtual environment and cached files. A .env file may hold passwords. List them in .gitignore.
.venv/__pycache__/*.pyc.env*.logExample 1 · Which files does .gitignore hide?
ignored_names = (".env",)ignored_endings = (".pyc", ".log")files = ["main.py", "main.pyc", "debug.log", ".env", "README.md"]
for name in files: hidden = name in ignored_names or name.endswith(ignored_endings) print(name, "ignored" if hidden else "tracked")main.py tracked main.pyc ignored debug.log ignored .env ignored README.md tracked
What this code does
- A file is ignored when its name or ending matches a rule.
main.pyandREADME.mdstay tracked, which is what we want.
Git ignores every file that matches a line. Add .gitignore before the first commit. A file that is already committed stays tracked, so remove it with git rm --cached <file>.
requirements.txt
requirements.txt is a text file that lists the packages a Python project needs, one per line, usually with exact versions. pip can install them all with one command.
Other people need the same packages you use. Write them in a text file, one per line, with exact versions.
pip freeze > requirements.txtpip install -r requirements.txtExample 2 · Reading requirements.txt
text = "requests==2.32.3\nflask==3.0.3\n"
for line in text.splitlines(): name, version = line.split("==") print(f"{name} -> {version}")requests -> 2.32.3 flask -> 3.0.3
What this code does
- Each line holds a package name,
==, and an exact version. - Exact versions mean everyone installs the same code.
pip freeze prints every package in your active environment with its version. The first command saves that list. The second installs a list on another computer.
Run it on a new computer
This is what a friend does after cloning your project. The virtual environment keeps its packages apart from the rest of the computer. Only the activate command differs.
On Windows
On Windows, use PowerShell inside the project folder.
- Create the environment:
python -m venv .venv. - Activate it:
.venv\Scripts\activate. - Install the packages:
pip install -r requirements.txt. - Run the program:
python main.py.
Example 3 · Installing from requirements.txt
Runs in: Your terminal
pip install -r requirements.txtCollecting requests==2.32.3 Using cached requests-2.32.3-py3-none-any.whl Successfully installed requests-2.32.3
What this code does
- pip reads the file and installs every package in it.
- The exact lines you see depend on your packages and pip version.
What the README must say
The README is the first file a visitor reads. It should answer four questions without making them guess.
- What is it? One or two sentences.
- How do I install it? The commands from the previous section.
- How do I run it? One command, and what it prints.
- Where do I ask for help? An issues link or an email.
Next step
Check your understanding
7 quick questions