Python Project Folder Structure: Files, Folders, venv, src, tests, data, and Git
Quick Answer
A good Python project keeps code, data, tests, docs, and environment files in predictable places.
Beginner rule:
project/
README.md
requirements.txt
.gitignore
src/
data/
tests/
.venv/Commit your code. Do not commit .venv.
Last verified: June 9, 2026.
Official Links
- Python packaging guide: https://packaging.python.org/
- Python
venvdocs: https://docs.python.org/3/library/venv.html - Git downloads: https://git-scm.com/downloads
- Git book: https://git-scm.com/book/en/v2
What You Will Learn
By the end, you should be able to:
- create a clean project folder
- know where code, data, notebooks, and tests go
- choose between
requirements.txtandpyproject.toml - write a basic README
- protect secrets with
.gitignore - avoid messy beginner layouts
1. Small Practice Script Structure
For one tiny script:
python-practice/
hello.pyThis is fine for day one.
Once you use packages, data files, notebooks, or tests, use a real structure.
2. Recommended Beginner Project Structure
learning-analysis/
README.md
requirements.txt
.gitignore
src/
analyze.py
data/
sample.csv
tests/
test_analyze.py
.venv/Meaning:
| Item | Purpose | Commit? |
|---|---|---|
README.md | explains the project | yes |
requirements.txt | package list | yes |
.gitignore | ignored files list | yes |
src/ | Python code | yes |
data/ | small safe data files | maybe |
tests/ | test files | yes |
.venv/ | local environment | no |
3. Data Science Project Structure
pandas-project/
README.md
requirements.txt
notebooks/
exploration.ipynb
src/
clean_data.py
build_features.py
data/
raw/
learners.csv
processed/
learner_features.csv
reports/
summary.md
tests/
test_clean_data.py
.gitignore
.venv/Use this when you have CSV files, notebooks, charts, and reusable cleaning code.
4. App Or CLI Project Structure
content-review-cli/
README.md
pyproject.toml
src/
content_review/
__init__.py
app.py
models.py
tests/
test_app.py
.gitignore
.venv/This structure is better for larger apps and importable modules.
5. Notebook-Friendly Project Structure
notebook-project/
README.md
requirements.txt
notebooks/
analysis.ipynb
src/
helpers.py
data/
input.csv
outputs/
chart.png
.gitignore
.venv/Keep notebooks in notebooks/. Move reusable code to src/.
6. What README.md Should Include
README.md explains the project.
Minimum useful README:
# Learning Analysis
## Goal
Analyze learner activity from a CSV file.
## Setup
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
## Run
python src/analyze.pyFor Windows, include PowerShell setup too:
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt7. What .gitignore Should Include
Beginner .gitignore:
.venv/
__pycache__/
*.pyc
.env
.DS_Store
.ipynb_checkpoints/Use .env for secrets locally, but never commit it.
Example .env:
API_KEY=do-not-commit-this8. requirements.txt vs pyproject.toml
Use requirements.txt for simple learning projects:
pandas==2.3.0
matplotlib==3.10.0Install:
python -m pip install -r requirements.txtUse pyproject.toml for modern project tooling, especially with uv:
uv init my-project
uv add pandas matplotlibBeginner rule:
- use
requirements.txtfor simple posts and exercises - use
pyproject.tomlfor uv or package-style projects
9. Where Data Files Should Go
Small safe files:
data/sample.csvLarger data projects:
data/raw/
data/processed/Do not commit private, paid, or sensitive data.
In code, use relative paths:
import pandas as pd
df = pd.read_csv("data/sample.csv")10. Where Tests Should Go
Use:
tests/
test_clean_data.pyTests help catch mistakes after edits.
Simple test:
def test_total():
assert 2 + 3 == 511. Git Basics
Install Git from:
https://git-scm.com/downloadsCommon workflow:
git init
git status
git add README.md src tests requirements.txt .gitignore
git commit -m "Initial project structure"Before git add ., make sure .venv/ and .env are ignored.
12. Bad Folder Structure
Avoid:
Desktop/
final.py
final2.py
final_new.py
chart latest.png
data copy.csv
passwords.txtThis becomes confusing very quickly.
13. Good Folder Structure
Prefer:
analysis-project/
README.md
src/
analyze.py
data/
learners.csv
tests/
test_analyze.py
requirements.txt
.gitignoreFAQ
Should .venv be inside or outside the project?
Inside the project is easiest for beginners. Just add .venv/ to .gitignore.
Should data files be committed?
Small original practice CSV files are fine. Private, huge, paid, or sensitive data should not be committed.
Should notebooks go in src/?
No. Put notebooks in notebooks/ and reusable Python code in src/.
Do I need tests as a beginner?
For tiny scripts, not always. For projects, yes. Even simple tests improve confidence.
Final Checklist
Your project folder should have:
README.md
requirements.txt or pyproject.toml
.gitignore
src/
data/ if needed
tests/ if it is a project
.venv/ ignored by GitWindows setup command:
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txtmacOS setup command:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txtGood structure reduces confusion before it starts.
Next in this series: Resolving Common Python Setup Errors: A Comprehensive Guide →