Python

audience developer
level all
topic Python
subtopic Installation

Best Way to Install Python

Setting up Python on Mac. Compare ways to install Python on macOS. Python tool complexity. Ways to manage Python projects. How to use Python version managers, package managers, and more.

Python is often the first programming language you'll install on a Mac. Until recently, a lack of standard development tooling made Python complicated. As a result, Python installation guides are often out of date or confusing. This guide cuts through the complexity, providing up-to-date, clear instructions for installing Python on macOS, showing you the best ways to install Python on a Mac and manage Python development, comparing all prominent Python installation methods for macOS -- from UV and Pyenv to Homebrew and the official installer.

Before you get started

You'll need a terminal application to install Python. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it's FREE and worth a try.

Python installation news

There is a new option for installing and managing Python, named UV, providing an extremely fast all-in-one tool for professional development with multiple projects. UV is 10-100x faster than other Python tools and can replace pip, pip-tools, pipx, virtualenv, pyenv, poetry, rye, and more. If you are writing Python programs, or just need Python for running programs and utilities, you should install UV, which installs Python automatically. For comparison, this guide also covers other Python installation options, including Pyenv, installation with Homebrew, and the official installer from the Python website.

Steps

Learn here about installation and development tools, including how to use version and package managers for your Python projects.

First, here's how you can install Python on Mac.

  1. Check macOS and update macOS if necessary.
  2. Check if Xcode Command Line Tools are installed.
  3. Install Python with UV (recommended).
  4. Set the Mac PATH for Python to make sure you use the correct version of Python.

Xcode Command Line Tools are required before installing Python (or any other programming language) because Python installation methods (like UV, Pyenv, and Homebrew) need basic Unix utilities that are not included by default in the macOS.

The Mac Path is an environment variable that controls where the operating system looks for executables. Setting the Mac PATH for Python is crucial because macOS will have multiple Python versions installed. Your PATH determines which version runs when you type python or python3. UV and Pyenv update the PATH automatically, but it's crucial to understand and check the PATH for troubleshooting.

Utilities or programming?

Before you install Python, consider why you need Python because different uses require different ways of installing Python.

There are two reasons for using Python on a Mac: running a program or work on programming projects. How you install Python (and how complicated it can be) depends on your needs.

The Python ecosystem has been evolving since 1991 and unlike newer programming languages, there are many choices for installing Python and managing projects.

Comparison of installation methods

| Method    | Best For                                 | Convenience | Speed     |
|-----------|------------------------------------------|-------------|-----------|
| UV        | Unified tools for coding projects   | ★★★★☆      | ★★★★★    |
| Pyenv     | Version switching, traditional workflow  | ★★★☆☆      | ★★★☆☆    |
| Homebrew  | Simple scripts with a single Python version    | ★★★★☆      | ★★★☆☆    |
| Pipx      | Stand-alone command-line utilities          | ★★★★☆      | ★★★☆☆    |

Python applications

You might wish to run a Python-based utility such as Youtube-dl, a command-line utility to download videos from YouTube, or Ruff, a popular Python code formatter. Utilities should be installed so they are available to all projects ("globally") but isolated from each other.

If you intend to use Python to run stand-alone applications and utilities, install UV to install the newest Python and isolate any program in its own environment. Alternatively, you can Install Pipx).

UV provides a built-in tool management system with uv tool install or the shorthand uvx command which serves a similar purpose to the older Pipx tool. As an example, here's the installation and use of the ruff code formatter:

# Run a tool in a temporary environment
$ uvx ruff check .

# Install a tool permanently
$ uv tool install ruff
$ ruff --version

Python programming

Any ambitious programming project will require installing Python packages, which is what distinguishes Python programming from running Python utilities. Packages installed for a programming project should be installed in a virtual environment, using a suitable tool to avoid installing Python packages or programs in ways that introduce the potential for dependency conflict. The need for a virtual environment isn't obvious in the early stages of learning Python. Virtual environments are not familiar to developers who use other programming languages because development tools for most other popular languages incorporate a project-based approach to package management (for example, Rust's cargo, Ruby's bundler, and JavaScript's npm).

UV is the best choice for package management because it automatically creates a virtual environment for each project, simplifying the process of managing Python projects.

Alternatively, you can use Pip, the standard tool for Python package management. For many years, Pip installed packages globally by default. Now, Pip prevents global package installation with error: externally-managed-environment if you attempt to install a package without a virtual environment (see error: externally-managed-environment). UV is a better choice unless you want to learn to use the older Python tools.

While UV offers impressive speed improvements and simplicity, it's worth noting it's newer than established tools like pip and venv. Often Python projects or tutorials will show use of older tooling, so familiarity with both approaches may be necessary.

How to install Python

If you're working on a programming project, or running a Python program, Install Python with UV. Many other articles show how to install Python with the python.org installer or Pyenv, a Python version manager. The other articles are not wrong; however, they don't describe the current best practice: UV simplifies Python with a one-stop project and package management solution that's 10-100x faster than traditional tools.

For installing Python, here's my guide that explains your options:

Here's a brief look at the versions of Python you may already have and how to install Python.

System Python

You'll need Xcode Command Line Tools for software development, and with Xcode, Apple includes Python 3.9.6. As of October 2024, the latest Python version is 3.13. The system Python is for Apple development utilities, not you. You should install a newer version for your programming work, as the system Python has several limitations:

  1. It's an older version (3.9.6) that lacks newer language features and optimizations
  2. Apple uses it for their own system scripts and utilities, so modifying it could break macOS functionality
  3. System updates may overwrite your changes or installed packages
  4. It has restricted permissions that can cause permission errors when installing packages

While some developers use the system Python 3.9.6 for quick scripts, it's not suitable for serious development. Some developers set an alias python3 to python to use the system Python and avoid the error zsh: command not found: python. However, for any real programming work or package installation, it's better to Install Python with UV to avoid permission problems, dependency conflicts, and outdated language features.

Install Python with Pipx

You can install Pipx with Homebrew, installing the newest Python as a dependency. if you want to use Python to run stand-alone applications and utilities. However, I recommend to Install Python with UV so you'll have a unified tool system.

Pipx is not a good option for installing Python for programming projects and developing software.

Install Python with UV

For programming projects, install Python with UV or install Python with Pyenv to better manage versions, virtual environments, and software packages.

If you will be programming in Python, UV is the new favorite for installing and managing Python because it offers a single coherent setup and packaging system, eliminating the need for separate tools such as pip, pyenv, and venv for managing versions, software libraries, and environments.

To install UV, run:

$ curl -LsSf https://astral.sh/uv/install.sh | sh

To install Python with UV:

$ uv python install

To install a specific Python version:

$ uv python install 3.12

Here's how to manage a project with UV if your programming project is more complex than a simple script:

# Create a new Python project
$ uv init myproject

# Add dependencies
$ uv add requests

# Run commands in the project environment
$ uv run python -c "import requests; print(requests.__version__)"

# Create a lockfile for reproducible builds
$ uv lock

Here uv init myproject creates both the directory structure and the pyproject.toml file so you can add a library (requests in this example).

Other Python installation options

It's good to know about other ways that developers install Python, so you know you are making the best choice.

Install Python with Homebrew

You can install Python with Homebrew, the Mac software package manager. You may already be using Homebrew to install other software packages. The Homebrew-installed Python is appropriate if you need to write a simple script in Python.

The Homebrew Python gets complicated and trouble-prone as soon as you need to install packages or work with different versions. If you anticipate a need to install a Python package, install UV.

Install Python with Pyenv

Pyenv is important if you have more than one Python programming project and must switch among Python versions. Use Pyenv rather than UV if you prefer to use the default Python development tools of Venv (for virtual environments) and Pip (for package installation). I find Pyenv, Venv, and Pip are more cumbersome than UV but you'll find older tutorials take this approach.

Pyenv is not needed when using UV because UV includes built-in version management capabilities, allowing you to install and switch between different Python versions:

# Install multiple Python versions
$ uv python install 3.11 3.12

# View installed Python versions
$ uv python list

# Pin a project to a specific Python version
$ uv python pin 3.11

Don't use the official Python installer

The official installer package from the Python website adds files to /usr/local/bin, modifies your Mac PATH, and installs the latest Python version in the macOS /Library/Frameworks folder. Though it's the official Python website installer, most Python developers avoid using it because it clutters a Mac in ways that are difficult to manage.

Managing Python

Installing Python is not enough to start a programming project. You'll need to know about version managers, package managers, and virtual environments.

For a single project you'll need to install, update, and remove software packages and manage dependencies with a package manager. When you work on more than one Python project, you will need an isolated environment for each project, each with its own Python version and packages, using a version manager and environment manager.

Compared to other programming languages like Rust or Ruby, a lack of standard tooling for development makes Python more complicated. That's why UV is beneficial, offering a unified tool system.

Version managers

Version managers allow you to install Python versions and switch among them easily.

If you maintain more than one Python project, you'll want to freeze a version for a project and switch to another version for other projects. UV makes it easy to install and switch among different Python versions with its built-in Python version manager. Alternatives are Pyenv or Conda (popular for data science and machine learning projects). You can also consider Mise or Asdf, version managers for multiple languages such as Python, Node, and Ruby. Some developers use Docker, a containerization tool, for version management. Docker is useful to containerize a complete software system such as a Python application and databases but it's overkill for simply switching Python versions among projects.

Here's how to Install UV or Install Pyenv so you have a version manager.

Package managers

Package managers allow you to download, install, and update software libraries and their dependencies.

Python is popular because of many software libraries ("packages") offered through the Python Package Index (PyPI). Any software project is a hierarchy of packages that provide basic functionality, alongside custom code that adds unique features for the specific application. Some packages enable connection to databases or APIs. Other packages make development more efficient, for example, packages for testing. You'll need a package manager to install, update, and remove software packages. Most packages depend on other external software libraries; the package manager must fetch and install any dependencies required by a package ("dependency resolution").

Pip is the standard package manager for Python, included with any version of Python since Python 3.3. Here's how to install Pip and how to install Python packages with Pip. Pip specifies packages in a requirements.txt file. Newer package managers use a pyproject.toml file instead. Updating a package with pip may not automatically update all of its relative dependencies which can lead to conflicts.

UV provides a much faster alternative to pip with the same interface:

# Create a virtual environment
$ uv venv

# Install packages (`requests` in this example)
$ uv pip install requests

# Compile requirements with dependency locking
$ uv pip compile requirements.in -o requirements.txt

Other alternatives include Pipx, Pipenv, Conda, PDM, and Poetry. These alternatives provide more robust dependency management, platform independence, and a better integrated workflow for Python package management than pip alone.

Environment managers

Use an environment manager to create a virtual environment for project isolation.

What is a virtual environment?

A virtual environment is an isolated, self-contained directory that contains a Python installation and package libraries specific to a single project. Think of it as a "sandbox" where you can install packages without affecting other projects or your system Python. Virtual environments solve a critical problem in Python development:

If Project A needs version 1.0 of a package and Project B needs version 2.0 of the same package, installing either version globally would break one of your projects. Virtual environments allow each project to have its own separate set of dependencies.

Why are virtual environments needed?

Environment managers are needed because pip installs packages globally which can lead to conflicts (dependency hell). Other programming languages like JavaScript or Ruby provide options to install packages locally (within a single project) as well as globally (system-wide for all projects).

There are two primary Python tools for creating virtual environments:

  • Venv - a built-in Python package since Python 3.3
  • Virtualenv - a more powerful third-party tool with additional features

These tools create a directory structure containing a Python interpreter and libraries, allowing pip to install packages into an isolated environment that doesn't share libraries with other projects.

If you use UV as an all-in-one tool, you won't need to manage venv or virtualenv explicitly as UV handles virtual environments automatically behind the scenes. However, you can still create virtual environments manually with:

$ uv venv

Project configuration files

Development tools are configured with project-specific files but only recently has there been a move to standardize on pyproject.toml and there still are no standards for dependency lock files.

To manage a Python project, you'll need a pyproject.toml file in your project root. The pyproject.toml file was adopted by the Python community in 2016 with the PEP 518 standard. The Python pyproject.toml file is equivalent to Node.js's package.json file, Ruby's Gemfile, or the Cargo.toml file used in a Rust project managed by Cargo.

UV automatically creates and manages the pyproject.toml file when you run uv init to start a new project:

$ uv init myproject

Lock files

Lock files are critical tools that freeze or "lock" your project's dependencies to specific versions, ensuring everyone working on a project uses identical package versions.

Why lock files matter:

  1. Team development consistency: Without lock files, two developers can run pip install -r requirements.txt and get different package versions, leading to "works on my machine" problems. Lock files ensure everyone on your team has identical dependencies.

  2. Reliable deployments: When deploying to production, you need certainty that the code will run exactly as it did in development and testing. Lock files guarantee that your production environment uses the exact same package versions that you tested with.

  3. Reproducible builds: Lock files allow you to rebuild your environment exactly as it was at any point in time, which is crucial for debugging issues that may have arisen with specific dependency versions.

  4. Deterministic testing: Automated testing becomes more reliable when the testing environment always uses identical package versions.

Unlike JavaScript (`package-lock.json), Ruby (Gemfile.lock), and Rust (Cargo.lock), Python has struggled with standardizing lock files. A proposed standard (PEP 665) was rejected in 2021, leaving each package manager to implement its own solution.

UV provides a universal lockfile system that works across all Python projects, making dependency management more consistent:

# Create a lockfile for your project
$ uv lock

# Sync your environment with the lockfile
$ uv sync

When a developer joins your team or you deploy to a new environment, running uv sync will install the exact versions specified in the lock file, ensuring perfect consistency across all environments.

Building and publishing packages

Most Python beginners won't build and publish Python software packages to the Python Package Index (PyPI). However, it's worth learning how it's done, even if you just make a simple package for sharing code among your projects. UV supports building and publishing packages:

# Build your package
$ uv build

# Publish your package to PyPI
$ uv publish

Common errors

You may encounter these errors when you are getting started with Python. See the guides for help:

Learning Python

Due to Python's popularity, there are hundreds of courses, books, and videos for getting started with Python. Here is the book I recommend for beginning programmers:

If you are coming to Python from another programming language, try:

What's next

My mac.install.guide is a trusted source of installation guides for professional developers. Take a look at the Mac Install Guide home page for tips and trends and see what to install next.