How to create a new Python project with Codex

Use an interactive Codex session to scaffoldGenerate the initial file and folder structure for a new project. a Python project with uv, Ruff, and pytest. Give it explicit commands and completion checks so the generated project is ready for further development.

Prerequisites

Install Codex CLI, uv, and Git. Sign in to Codex when prompted. These steps create a new local project; choose an unused directory name.

Open a session in an empty repository

Run these commands in a terminal, using PowerShell on Windows:

mkdir payments
cd payments
git init
codex --sandbox workspace-write --ask-for-approval on-request

Git reports that it initialized an empty repository, then Codex opens an interactive session rooted in payments. Project writes are allowed; uncached package downloads may require network approval.

Ask Codex to create the project

Paste this prompt into the session. Replace the service requirements with the application being built:

Create a Python service named payments in the current directory.
Use uv init --package --name payments for the project layout.
Add FastAPI with uv add fastapi.
Add development tools with uv add --dev ruff pytest httpx.
Implement a GET /health endpoint returning {"status": "ok"}, with a test.
Configure Ruff for linting and formatting.
Write a README with setup and test commands.
Create AGENTS.md documenting uv commands and the verification commands.
Run uv run ruff check ., uv run ruff format --check ., and uv run pytest.
Fix failures, then summarize changed files and the actual check results.
Do not commit or push.

The --dev flag marks these tools as development dependenciesA package needed during development (testing, linting, formatting) that is not shipped to users of your project. Installed with the --dev flag. , keeping them out of production installs. uv run executes the command inside the project’s virtual environment, ensuring all dependencies are installed first.

The resulting project should include pyproject.toml, the uv.lock lockfileA file that records the exact version of every installed package, so everyone working on the project gets identical installs. , src/payments/, tests, README.md, and AGENTS.md. Review any additional dependencies before continuing. For broader scaffolding conventions, consult the Modern Python Project Setup Guide for AI Assistants.

Verify the generated project

Exit Codex with /exit, then run from the same directory:

uv sync --locked
uv run ruff check .
uv run ruff format --check .
uv run pytest
git status --short

The sync must finish without changing the lockfile. Ruff should report no lint errors and no files requiring formatting; pytest should report passing tests. Git lists the generated files, including untracked files that an ordinary diff omits.

Read pyproject.toml, AGENTS.md, and the generated code before committing. If checks fail or could not run, reopen Codex in this directory with the failing output and ask it to resolve the cause. For ongoing configuration, see Use Codex for Python development.