Production-Ready Python Project Checklist for Developers

Production-Ready Python Project Checklist: Before GitHub, Portfolio, CI, or Deployment

Quick Answer

Before publishing or deploying a Python project, verify:

• setup is documented
• dependencies are reproducible
• tests pass
• lint and formatting checks pass
• secrets are not committed
• logs are useful
• config is documented
• CI runs automatically

This checklist is for learners, portfolio builders, and developers preparing a Python project for public review or production use.

Last verified: June 26, 2026.

1. Project Structure Checklist

Your project should have:

README.md
.gitignore
.env.example
src/ or app code folder
tests/
pyproject.toml or requirements.txt

For packages and serious apps, prefer:

src/
  package_name/
    __init__.py

For data projects, add:

data/
  raw/
  processed/
notebooks/
outputs/

2. README Checklist

Your README should answer:

• What does the project do?
• Why does it exist?
• Which Python version is required?
• How do I create the environment?
• How do I install dependencies?
• How do I run the project?
• How do I run tests?
• Which environment variables are required?
• What are the main folders?

Minimum commands:

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
pytest

For pyproject.toml:

python -m pip install -e ".[dev]"
pytest

3. Dependency Checklist

Confirm:

• dependencies are listed
• dev dependencies are separated when possible
• dependency file is committed
• .venv is not committed
• install command works from a fresh clone

Acceptable beginner setup:

requirements.txt

Preferred modern setup:

pyproject.toml

uv setup:

pyproject.toml
uv.lock

4. Testing Checklist

Confirm:

• tests live in tests/
• tests run with pytest
• important success cases are covered
• important error cases are covered
• tests do not depend on your desktop paths
• tests do not call real paid APIs
• file tests use temporary paths
• config tests use isolated environment variables

Run:

pytest

Optional coverage:

pytest --cov=src --cov-report=term-missing

5. Code Quality Checklist

Run:

ruff check .
ruff format --check .

Confirm:

• imports are sorted
• no unused imports
• no undefined names
• formatting is consistent
• functions are reasonably small
• names describe intent
• exceptions are specific

If the project is important, add pre-commit.

6. Configuration Checklist

Confirm:

• .env is ignored
• .env.example exists
• required variables are documented
• defaults are safe for local development
• production values are not hard-coded
• missing required config fails clearly

Example .env.example:

DATABASE_URL=sqlite:///local.db
API_KEY=
LOG_LEVEL=INFO

7. Secrets Checklist

Search before publishing:

rg "api_key|secret|password|token|BEGIN PRIVATE KEY|sk-"

Confirm:

• no real API keys
• no database passwords
• no private tokens
• no .env in Git
• no secrets in logs
• no secrets in screenshots or notebooks

If a secret was committed, rotate it.

8. Logging Checklist

Confirm:

• app code uses logging, not only print
• log level is configurable
• errors include useful context
• secrets are masked
• background jobs log start and finish
• failures are visible

Basic setup:

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

9. Data Checklist

For data projects:

• raw data is preserved
• private data is not committed
• sample data is safe and small
• generated outputs are ignored unless needed
• cleaning steps are reproducible
• notebooks do not contain hidden secrets

Good .gitignore additions:

data/private/
outputs/
*.sqlite
*.db

Commit small synthetic examples when they help users run the project.

10. Git Checklist

Before pushing:

git status
git diff --check

Confirm:

• commits are focused
• commit messages are clear
• generated junk is not staged
• .gitignore is working
• README is updated
• tests pass

Good commit:

Add pytest coverage for config loader

Weak commit:

final changes

11. CI Checklist

For GitHub Actions, run:

• install dependencies
• lint
• format check
• tests

Example:

name: Python checks

on: [push, pull_request]

jobs:
  checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install -e ".[dev]"
      - run: ruff check .
      - run: ruff format --check .
      - run: pytest

CI should match local commands.

12. Documentation Checklist

Add docs when the project has:

• setup complexity
• environment variables
• commands
• architecture decisions
• APIs
• data pipelines

Useful docs:

docs/
  architecture.md
  decisions.md
  operations.md

Do not write huge docs nobody updates. Write small docs that answer real questions.

13. Release Checklist

Before a release:

• version is updated
• changelog is updated
• tests pass
• CI is green
• README examples still work
• migration steps are documented
• rollback plan exists for deployed apps
• secrets are configured outside Git

For packages, verify build:

python -m build

For apps, verify start command from a clean environment.

14. Portfolio Checklist

If this project is for your portfolio:

• README has screenshots or sample output
• problem statement is clear
• setup takes less than 10 minutes
• demo data is included
• tests are present
• code is organized
• no secrets or private files
• project has a clear "What I learned" section

Recruiters and reviewers should understand the project quickly.

15. Final Scorecard

Use this scorecard:

If any row is weak, fix it before publishing.

16. FAQ

Does every Python project need CI?

No. Use CI for projects you share, deploy, or maintain over time.

Does every project need pyproject.toml?

No. Beginner scripts can use requirements.txt. Use pyproject.toml for modern apps, packages, and tool configuration.

How many tests are enough?

Enough to protect important behavior. Start with critical parsing, validation, calculations, and error cases.

Should I publish my .env.example?

Yes. It documents required variables without exposing real values.

Should I publish sample data?

Yes, if it is small, safe, and synthetic or publicly reusable. Do not publish private or copyrighted data.