Mac Python
Setting up Python on Mac. Options 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 programing 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. But mac.install.guide is up to date, showing you the best ways to install Python and manage Python development. Save the URL!
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 Rye, providing an all-in-one tool for professional development with multiple projects. However, if you just need Python for running programs such as utilities or scripts, you should install Pipx, which installs Python automatically. This guide also covers other Python installation options, including Pyenv, installation with Homebrew, and the official installer from the Python website.
Steps
You'll learn 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.
- Check macOS and update macOS if necessary.
- Check if Xcode Command Line Tools are installed.
- Install Python with Pipx (for scripts and utilities).
- Install Python with Rye (recommended for programming).
- Set the Mac PATH for Python to make sure you use the correct version of Python.
The Python ecosystem has been evolving since 1991 and unlike newer programming languages, there are many choices for installing Python and managing projects. Before you install Python, consider why you need Python because different uses require different ways of installing Python.
Utilities or programming?
Developers have two common 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.
Python applications
If you only need Python to run stand-alone applications and utilities, it's best to install Pipx, which installs the newest Python as a dependency and isolates any program in its own environment (see my guide Install Pipx). Python-based utilities are becoming more common with the increasing popularity of AI and there are also stand-alone programs that require Python to run, such as Youtube-dl, a command-line utility to download videos from YouTube. Python programming tools, such as Ruff, a popular Python code formatter, also should be installed with Pipx because you'll need to install programming tools so they are available to all projects ("globally") but isolated from each other. Installing Python with Pipx is ideal for utilities and programming tools, but keep in mind it's not a good choice for programming projects.
Python programming
Any ambitious programming project will require installing Python packages, which is what distinguishes Python programming from running Python utilities. Any packages installed for a programming project should be installed in a virtual environment, using a suitable tool (such as Venv or Rye) 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. And 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). The standard tool for Python package management is Pip. 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). Rye is a better choice than Pip for package management because it automatically creates a virtual environment for each project, simplifying the process of managing Python projects.
The complications of installing packages and avoiding dependency conflicts are what distinguish Python programming from running Python utilities.
How to install Python
If you're running a utility or script, install Pipx, which installs the newest Python as a dependency and isolates any program in its own environment. See the article Install Pipx.
If you're working on a programming project, use Rye to install Python and manage your project (see Install Python with Rye). 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: Rye simplifies Python with a one-stop project and package management solution.
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 2023, the latest Python version is 3.12. You should install a newer version for running Python programs or programming and you shouldn't use the system Python -- it's for Apple development utilities, not you.
Some developers use the system Python 3.9.6 for simple scripts or command-line utilities. To avoid the error zsh: command not found: python some developers set an alias python3 to python to use the system Python. However, in general, using the system Python for installing and running programs or developing software quickly gets complicated, requiring expertise. And experts prefer to install Pipx to run programs or install Python separately and set up a proper development environment for programming.
Install Python with Pipx
If you will only use Python to run stand-alone applications and utilities, it's best to install Pipx, which you can install with Homebrew, and installs the newest Python as a dependency.
For programming projects, install Python with Pyenv or install Python with Rye to better manage versions, virtual environments, and software packages.
Install Python with Rye
If you will be programming in Python, Rye 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.
If your programming project is more complex than a simple script, use Rye to install Python and software libraries.
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. As soon as you need to install a Python package, install Pipx (for applications) or use Pyenv, Venv, and Pip (for programming).
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 Rye 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 Rye but you'll find older tutorials take this approach.
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.
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. Rye makes it easy to install and switch among different Python versions. 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 Rye or Install Pyenv so you can compare version managers.
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 will fetch and install any dependencies required by that package.
Pip is the standard package manager for Python, included with any version of Python since Python 3.3. 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.
Alternatives to Pip include Rye, Pipx, Pipenv, Conda, PDM, and Poetry. Alternatives provide more robust dependency management, platform independence, and a better integrated workflow for Python package management. The blog post Python Has Too Many Package Managers provides a good overview.
Here's how to install Pip and how to install Python packages with Pip.
Environment managers
Use an environment manager to create a virtual environment for project isolation.
Often we need different versions of packages for different projects. Environment managers are needed because pip installs packages globally which can lead to conflicts (dependency hell). Other software languages (JavaScript or Ruby, for example) provide options to install packages locally (within a single project) as well as globally (system-wide for all projects). There are two Python tools for creating virtual environments and using different versions of packages. Venv is a built-in Python package. Virtualenv is a more powerful tool with additional features. These tools allow pip to install Python packages into a virtual environment with its own installation directories, that doesn’t share libraries with other virtual environments.
If you use Rye as an all-in-one tool, you won't need venv or virtualenv for environment management.
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.
Lock files
Ideally, package managers provide an option to freeze or lock package dependencies. This feature ensures that projects use specific versions of dependencies, avoiding clashes or failures as dependencies are updated. Node.js has package-lock.json, Ruby has Gemfile.lock, and Rust has Cargo.lock. Python lacks standardization of package lock files (a proposal PEP 665 was rejected in 2021). Each package manager has a different lock file.
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. Rye supports building and publishing packages. Under the hood, Rye uses build and Twine to build and publish packages.
Common errors
You may encounter these errors when you are getting started with Python. See the guides for help:
- zsh: command not found: python if Python is not installed or the [Mac PATH] is not set correctly
- zsh: command not found: pip if you are trying to install a Python program or package
- error: externally-managed-environment if you try to install a Python package globally without a virtual environment
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.