Python Example Project
Python example project for Mac. A small uv project to run, change, and build on, with a package from PyPI and instructions for an AI agent.
Use the Python example project to see how a real Python project works on a Mac, then base your own programs on it.
Many people start Python with a single file and the python command. That works until you want to use a package someone else wrote. Finding a tutorial that says to run pip install often leads to failure on a Mac. Experienced Python developers know to manage each program in its own project folder, with a private environment and a list of the packages it uses, so the program runs the same way next month or on another Mac. The example project gives you that setup, already working, with instructions that tell an AI agent how Python is set up on your Mac.
My free app, "Set Up Your Mac for Python", offers to create the example project after it installs Python. In this article I explain what is in the project, how to run it, how to add packages, and how to use it with an AI agent.
Starting a Python project is one step in setting up your Mac for development. See the complete Mac setup checklist.
Before you get started
I recommend using our free app to set up Python and the example project on your Mac. It is a FREE Mac app that installs uv and Python, sets the PATH so the python command works, and verifies Python is working. Then it offers to create the example project in your Projects folder. Here are all the details about the app before you download. Then download it:
The example project in "Set Up Your Mac for Python"
After the app installs Python, it checks that Python works by installing a package into a temporary project, then deletes that project. The next screen, "Install a Python example project?", offers you a project that does the same thing and stays on your Mac. It has three buttons:
- Install in Projects - creates the project in a Projects folder in your home directory, at
~/Projects/Python-Example-Project. - Choose my folder… - creates the same
Python-Example-Projectfolder inside a folder you choose instead. - Skip - moves on without creating a project.
The app never writes into a folder that already exists, so it can't overwrite your files. If you skip the screen, the app offers the project again the next time you run it. Once the project exists, the app shows "Your Python example project is set up" and moves on.
Many developers keep their projects in a folder such as ~/Projects instead of Documents, because macOS protects the Documents folder and iCloud may sync it. The app follows the same practice. The article Starter Projects explains both problems.
Run the example project
Here's how to run the program in the project. Open a terminal application and move into the project folder with the cd command. If you clicked "Install in Projects", run:
$ cd ~/Projects/Python-Example-Project
If you chose a folder inside Documents, macOS asks whether to allow your terminal application to open files there the first time it does. Click "Allow", or commands in the folder fail with "Operation not permitted".
Run the program with uv run, the command that runs Python code inside a uv project:
$ uv run source/hello.py
You'll see a cow saying "Python is working on your Mac":
_____________________________
| Python is working on your Mac |
=============================
\
\
^__^
(oo)\_______
(__)\ )\/\
||----w |
|| ||
The cow shows that four things work:
- Python is installed.
- The project has its own private environment.
- A package,
cowsay, was downloaded from the Python Package Index (PyPI, the public collection of Python packages). - Your code imported the package and ran.
The uv run command does the setup for you. Before it runs the file, it creates the project's environment if it is missing, in a hidden folder named .venv, and installs the packages listed in the project's pyproject.toml file. On the first run you'll see a few lines from uv as it does this. The first run may take a few seconds while uv downloads the package. After that, the program starts at once.
Always start the program with uv run. If you type python source/hello.py instead, Python looks for packages outside the project's environment. You'll see ModuleNotFoundError: No module named 'cowsay'.
What's in the project folder
Here's what the app puts in the folder. Names that start with a dot are hidden in the Finder until you show hidden files by pressing Command + Shift + . (period).
README.md- the "Start here" file, with the commands to run and prompts to try with an AI agent. Open it first, in a code editor or a Markdown editor.source/hello.py- the program. It importscowsayand shows the cow.pyproject.toml- the project's settings, including its list of packages. Theuv addcommand edits it for you. See the article What Is pyproject.toml?.AGENTS.md- instructions for an AI agent. Codex and the Warp agent read it.CLAUDE.md- a single line,@AGENTS.md, which makes Claude Code readAGENTS.mdtoo, so every AI agent gets the same instructions..gitignore- a list of files that Git leaves out of the project's history, such as the.venvfolder and any.envfile of secrets. See the article What Is a .gitignore File?..claude,.codex, and.agents- hidden folders that hold the same agent skill,add-a-package, for Claude Code, Codex, and other AI agents. See the article What Are the .claude, .codex, and .agents Folders?.
After the first uv run, two more appear:
.venv- the project's private environment, which holds its packages. Don't edit it by hand. You can delete it if something goes wrong in it. The nextuv runcreates it again. See the article What Is a .venv Folder?.uv.lock- a record of the exact version of every package, written by uv. Keep it with the project, so the project gets the same versions on another Mac.
Change the program
Open source/hello.py in a code editor, such as Zed or VS Code. Near the bottom of the file you'll find this line:
cowsay.cow("Python is working on your Mac")
Change the words inside the quotes and save the file. Then run uv run source/hello.py again to see the cow say your words. The cowsay package has other characters too. Change cowsay.cow to cowsay.dragon, cowsay.tux (the Linux penguin), or cowsay.trex to see them.
You can add your own .py files to the source folder and run each one the same way, with uv run source/<file>.py.
Add a package with uv add
Here's how to add a package someone else wrote. In the project folder, run uv add with the package's name. For example, the pyfiglet package turns text into large letters:
$ uv add pyfiglet
The uv tool downloads the package, installs it into the project's .venv folder, and adds it to the list in pyproject.toml. Try the package with a one-line Python program, run inside the project with uv run:
$ uv run python -c "import pyfiglet; print(pyfiglet.figlet_format('Hello'))"
You'll see "Hello" in large letters made of characters. To remove a package, run uv remove with its name:
$ uv remove pyfiglet
When a tutorial tells you to run pip install with a package name, run uv add with the same name instead.
Why pip install doesn't work here
Many Python tutorials still tell you to run pip install. On a Mac set up with uv, the command fails with zsh: command not found: pip. Apple provides no pip command. The uv tool doesn't put one in a project's environment either. If your Mac has another Python, such as Homebrew's, pip3 install fails with error: externally-managed-environment, because that Python won't install packages outside an environment. The rule protects a Python that other software on your Mac depends on.
You don't need to work around either error. In a uv project, uv add puts each package in the project's own environment. The articles Command not found: pip and Fix: error: externally-managed-environment on Mac explain the errors in more detail.
Use the project with an AI agent
The example project is set up for an AI agent such as Claude Code or Codex. Its AGENTS.md file tells the agent that uv manages Python on your Mac, so the agent uses uv add and uv run instead of pip install and the bare python command. Without those instructions, an AI agent may suggest pip install, the same as older tutorials. The file also asks the agent to explain each step in plain language and to ask before it installs software or deletes files.
Open the project folder in an AI agent:
- Claude Code - in a terminal application,
cdinto the folder and runclaude. See the article Install Claude Code on Mac. - Claude Desktop - click
Codeat the top of the window, then choose the folder withOpen folder…. The Code tab needs a paid Claude plan. See the article Claude Code and Claude Desktop Compared. - Codex - in a terminal application,
cdinto the folder and runcodex, or open the folder in the ChatGPT desktop app. - Warp - open the folder in Warp and use its agent, which needs a Warp account and AI credits.
Then try a prompt from the project's README.md:
- "What's in this folder, and what can you help me build here?"
- "Change hello.py to say something else, then run it."
- "Add a package that makes ASCII art and show me how to use it."
The project's add-a-package skill tells the agent how to add a package with uv and how to explain a pip error if you've seen one. The article Starter Projects explains more about working with an AI agent in a project folder, including how to save versions of your work with Git.
Start your own Python project
When you're ready to write a program of your own, make a new project for it. Here's how to make one with the same simple layout as the example project. The --no-package option creates a project for a program you run, with a main.py file to start from, instead of a package you'd publish for others to install:
$ cd ~/Projects
$ uv init --no-package my-project
$ cd my-project
$ uv run main.py
You'll see Hello from my-project!. The uv init command also creates a pyproject.toml, a README.md, a .gitignore, and a Git repository for the project. Add packages with uv add, as in the example project.
To give an AI agent the same instructions in your new project, copy AGENTS.md and CLAUDE.md from the example project into the new folder, along with the hidden .claude, .codex, and .agents folders. Then ask the agent to update AGENTS.md to describe the new project.
If you'd like to run Python a few lines at a time and see tables and charts beside your code, see the article Install Jupyter on Mac. The article uv for Python on Mac explains more of what uv can do.
Troubleshooting
ModuleNotFoundError: No module named 'cowsay'
You ran the program with python source/hello.py or python3 source/hello.py. Those commands start Python outside the project's environment, which doesn't have the project's packages. Run the program with uv run source/hello.py instead.
zsh: command not found: uv
The terminal can't find uv. If the terminal window was open while the app installed uv, close it and open a new window, which reads the updated settings. If the error stays, see the article Command not found: uv.
Operation not permitted
If you clicked "Don't Allow" when macOS asked whether your terminal application could use the Documents folder, commands in the project fail with "Operation not permitted". Turn access back on in System Settings > Privacy & Security > Files & Folders, under your terminal application. Don't turn on Full Disk Access to fix it.
Start over with a fresh copy
You can't break anything important in the example project. To start over, drag the Python-Example-Project folder to the Trash. The next time you run "Set Up Your Mac for Python", it offers to create the project again.
Continue setting up your Mac
Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.