# Creating an Effective Python Project Folder Structure
URL: https://madhudadi.in/blog/posts/python-project-folder-structure-best-practices-guide
Published: 2026-06-10
Tags: python, setup
Read time: 42 min
Difficulty: beginner
> Learn how to organize Python projects with clean folders, .venv, src, tests, data, README, requirements.txt, pyproject.toml, .gitignore, and Git.# 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:

```text
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 `venv` docs: 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.txt` and `pyproject.toml`
- write a basic README
- protect secrets with `.gitignore`
- avoid messy beginner layouts

## 1. Small Practice Script Structure

For one tiny script:

```text
python-practice/
  hello.py
```

This is fine for day one.

Once you use packages, data files, notebooks, or tests, use a real structure.

## 2. Recommended Beginner Project Structure

```text
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

```text
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

```text
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

```text
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:

```markdown
# 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.py
```

For Windows, include PowerShell setup too:

```markdown
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
```

## 7. What .gitignore Should Include

Beginner `.gitignore`:

```gitignore
.venv/
__pycache__/
*.pyc
.env
.DS_Store
.ipynb_checkpoints/
```

Use `.env` for secrets locally, but never commit it.

Example `.env`:

```text
API_KEY=do-not-commit-this
```

## 8. requirements.txt vs pyproject.toml

Use `requirements.txt` for simple learning projects:

```text
pandas==2.3.0
matplotlib==3.10.0
```

Install:

```bash
python -m pip install -r requirements.txt
```

Use `pyproject.toml` for modern project tooling, especially with uv:

```bash
uv init my-project
uv add pandas matplotlib
```

Beginner rule:

- use `requirements.txt` for simple posts and exercises
- use `pyproject.toml` for uv or package-style projects

## 9. Where Data Files Should Go

Small safe files:

```text
data/sample.csv
```

Larger data projects:

```text
data/raw/
data/processed/
```

Do not commit private, paid, or sensitive data.

In code, use relative paths:

```python
import pandas as pd

df = pd.read_csv("data/sample.csv")
```

## 10. Where Tests Should Go

Use:

```text
tests/
  test_clean_data.py
```

Tests help catch mistakes after edits.

Simple test:

```python
def test_total():
    assert 2 + 3 == 5
```

## 11. Git Basics

Install Git from:

```text
https://git-scm.com/downloads
```

Common workflow:

```bash
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:

```text
Desktop/
  final.py
  final2.py
  final_new.py
  chart latest.png
  data copy.csv
  passwords.txt
```

This becomes confusing very quickly.

## 13. Good Folder Structure

Prefer:

```text
analysis-project/
  README.md
  src/
    analyze.py
  data/
    learners.csv
  tests/
    test_analyze.py
  requirements.txt
  .gitignore
```

## FAQ

### 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:

```text
README.md
requirements.txt or pyproject.toml
.gitignore
src/
data/ if needed
tests/ if it is a project
.venv/ ignored by Git
```

Windows setup command:

```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
```

macOS setup command:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
```

Good structure reduces confusion before it starts.