What Is a .venv Folder?

What is venv. A .venv folder holds a Python project's own Python and packages. Why it is hidden on a Mac, how to use it, and why it stays out of Git.

A .venv folder holds a Python project's virtual environment, or "venv" for short. It gives the project its own python command and its own set of packages. The python command inside is a link to a Python installed elsewhere on your Mac, so the folder doesn't hold a full copy of Python. The packages belong to this project alone, so one project can use version 1.0 of a package while another uses version 2.0.

Python beginners typically think of Python as one program on their Mac, and of installing a package as adding to that one program. For beginners, pip install often fails with error: externally-managed-environment (most often when Python was installed by Homebrew). Experienced Python developers give every project its own virtual environment in a .venv folder. Nothing they install for one project can break another project. They can also use the Python that Homebrew installs. When something goes wrong, they delete the folder and build it again. With uv, the folder is created for you, so most days you won't need to think about it.

What's in a Project Folder? explains the other files and folders you'll find beside the .venv folder in a project. Python virtual environments are one step on the roadmap for setting up a Mac for coding.

Why use a virtual environment

On a Mac, you'll need a virtual environment as soon as you install Python packages for a project. macOS doesn't include Python. The python3 command that appears after you install the Xcode Command Line Tools is an old version (3.9.6) that you shouldn't use for your own projects, so you'll install a newer Python with Homebrew or uv. In general, it is better to use uv on Mac rather than install Python with Homebrew.

Homebrew marks its Python as "externally managed", which means pip won't install packages into it. Homebrew's documentation tells you to use a virtual environment instead. Fix: error: externally-managed-environment on Mac explains the error.

A virtual environment does more than avoid that error:

Each project gets its own packages - two projects can need different versions of the same package. Each gets the version it needs.
Your Mac's Python stays clean - packages go into the project's folder, not into the Python that Homebrew or uv installed. You don't need an administrator password.
It's disposable - if the environment breaks, delete the folder. uv rebuilds it from the list in pyproject.toml and the exact versions in uv.lock.
An AI agent's changes stay in the project - when Claude or Codex installs a package, it lands in the project's .venv. Nothing changes for your other projects.

Python's many tools, and uv

Python has no single standard tool for virtual environments. Python has included the venv tool since version 3.3, in 2012. The older third-party virtualenv tool still works. Project tools such as Poetry and Pipenv make virtual environments too, but by default they keep them in a folder elsewhere on your Mac, not in the project. conda, popular for data science, keeps its environments in its own folder and installs packages from its own sources. Each tutorial picks its own approach, which is why beginners get confused.

The tool that has emerged as the favorite is uv, from the company Astral. It installs Python, creates the .venv folder in the project's top folder, and installs the packages, all in one fast program. I recommend it, so this article uses it in its examples. How to Install Python on Mac compares uv with other ways to get Python. Install uv on Mac shows how to install it. Python on Mac lists all my Python articles.

Why .venv is hidden

The dot at the start of the name keeps the folder hidden and out of the way. The name .venv avoids a clash with .env files, which hold settings and secrets. On a Mac, the Finder hides any name that starts with a dot, so you won't see .venv until you show hidden files on Mac. A folder named venv, without the dot, is the same thing, only visible.

What's inside .venv

A virtual environment holds four things you might notice:

bin/ - the python command and the activate script. An environment made by Python's venv tool also has pip. One made by uv doesn't, because uv installs packages itself.
lib/ - the packages you installed for this project, in a folder named for the Python version, such as lib/python3.13/site-packages.
pyvenv.cfg - a short text file that records which Python made the environment.
.gitignore - a short file containing *, which tells Git to ignore the whole folder. Python 3.13 and later, and uv, write it.

Don't put your own code in .venv. Don't edit anything inside it. Python's documentation calls a virtual environment disposable, meaning you are able to delete it and make a new one at any time.

Create a .venv folder

With uv, you don't create the folder yourself. uv init starts a project without one. The first time you run the project with uv run, uv creates the .venv folder and installs the packages listed in pyproject.toml. What Is pyproject.toml? explains that file.

If you are not using uv, create the folder with Python's own venv tool. Open a terminal application, change to your project folder, and run this command with the Python you installed, such as Homebrew's:

$ python3 -m venv .venv

Activate a venv

You need this step if you are not using uv, or when you want to type python and other commands directly without uv run. Activation works the same in an environment made by uv.

Activating a virtual environment tells your shell to use the project's Python. Run this in the project folder:

$ source .venv/bin/activate

If you leave out source and type only .venv/bin/activate, you'll see zsh: permission denied followed by the path. The activate file isn't a program you can run. The word source tells your shell to read the file and change its own settings.

After you activate it, your prompt starts with the environment's name in parentheses. While it is active, the python command runs the one in .venv. In an environment made by Python's venv tool, pip does too. To check, ask which python your shell uses:

$ which python

You'll see a path that ends in .venv/bin/python. When you're done, run deactivate to go back to your normal shell.

No activation with uv run

With uv, you can skip activation. uv run finds the project's .venv folder each time, creates it if it is missing, and keeps it up to date with pyproject.toml and uv.lock.

This matters when an AI agent works on your project. Anthropic Claude runs each shell command with fresh settings, so activating a virtual environment in one command doesn't carry over to the next (Anthropic suggests activating it before you start Claude in the terminal). uv run works in every command, so the AGENTS.md file in the example Python project described in Starter Projects tells the AI agent to run files with uv run and add packages with uv add, never pip install. It is much easier to use Python if you tell the AI agent in the AGENTS.md file to use uv for Python.

Should .venv go in Git?

Python's documentation and uv's documentation both say to keep the virtual environment out of Git. The .gitignore file inside .venv already does that, so Git ignores the folder even when the project's own .gitignore doesn't list it (the .gitignore file article explains how these lists work).

What goes in Git is the list of packages, so anyone can build the same environment. In a uv project that list is pyproject.toml with uv.lock. In an older project it is requirements.txt.

Can I delete .venv?

You can delete .venv whenever it stops working, or to free space in a project you aren't using. Python's documentation says a virtual environment can't be moved or copied, so recreate it if you move or rename the project folder. When Homebrew upgrades its Python, virtual environments made from the old version can stop working.

To delete it, show hidden files in the Finder and move .venv to the Trash. In a uv project, the next uv run builds a new one. Without uv, create it again with python3 -m venv .venv, activate it, and reinstall the packages from requirements.txt with python -m pip install -r requirements.txt.

Now you can find the .venv folder in a Python project on your Mac, use it with or without uv, keep it out of Git, and rebuild it whenever it breaks.

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.