Python is easy to use, friendly to the beginner, and powerful enough to create robust software with for nearly any application. But it is still a piece of software like any other, meaning it can be complex to set up and manage.

In this article we’ll walk through how to set up Python the right way: how to pick the appropriate version, how to keep multiple versions from stepping on one another, and how to avoid all of the other sharp edges and potential pitfalls along the way.

Choose the right Python version and distribution

For the sake of compatibility with third-party modules, it is always safest to choose a Python version that is one major point revision behind the current one.

At the time of this writing, Python 3.8.1 is the most current version. The safe bet, then, is to use the latest update of Python 3.7 (in this case, Python 3.7.6). You can always try out the most recent version of Python in a controlled way — e.g., in a VM or a test machine — but going one version back guarantees the best compatibility with common third-party Python packages.

Python also comes in a variety of distributions, in much the same way Linux does. Unlike Linux, though, Python offers one, gold-standard, “official” edition you can always fall back on: CPython, the version provided by the Python Software Foundation at python.org. Again, this is the safest and most broadly compatible distribution, the one nobody gets fired for picking. (You might want to investigate other Python distributions later, since they address specific use cases you might have, but we won’t consider them here.)

One key choice you’ll need to make, especially on Windows, is whether to use the 32-bit or 64-bit version of Python. The most likely answer is 64-bit, for the following reasons:

• Most modern operating systems use a 64-bit edition of Python by default. Windows users can run 32-bit editions of Python on 64-bit Windows, but at a slight cost of performance. 
• 32-bit Python, and 32-bit apps generally, can access only 4GB of memory at a time. 64-bit applications don’t have this limit, hence many data analysis and machine learning tools for Python work best in 64-bit incarnations. Some are available only in 64-bit versions. 

The only time you should choose the 32-bit version of Python is if you’re stuck with a 32-bit version of Windows, or you need to use a third-party module that is available only in a 32-bit edition.

Install Python on Windows the smart way

Python installs on Windows in much the same way as any other application, by way of an installer that guides you through the setup process.

By default the Python installer for Windows places its executables in the user’s AppData directory, so that it doesn’t require administrative permissions. If you’re the only user on the system, you might want to place Python in a higher-level directory (e.g. C:Python3.7) to make it easier to find. The Windows installer lets you specify the target directory.

Choose the right Python installer for Windows

Python.org offers a number of different incarnations of Python for Windows. In addition to the 32-bit (“x86”) and 64-bit (“x86-64”) versions already mentioned, you can choose from the embeddable zip file, the executable installer, and the web-based installer. Here’s what those are all about:

• The executable installer is just an .EXE file that runs the setup process for Python. This is the easy default choice, and the most commonly used.
• The web-based installer is the same as the executable installer, except that it separately downloads the bits needed to perform the install. This dramatically reduces the size of the actual installer, but of course requires a network connection.
• The embeddable zip file is a self-contained, minimal copy of the Python runtime that fits in a single folder with no dependencies. It’s useful to bundle in when you want to distribute a Python app manually, or when you need a quick, one-off Python install to test something on the fly. But the embeddable zip doesn’t include pip or any of the other useful tools that come with a full install, so it’s for expert use only.

Install Python using a package manager for Windows

Yet another option is to use one of the package management systems that exist for Windows. NuGet, the package manager for .NET, offers Python in its repository. However, Python is provided there mainly for the sake of using it as a component in a .NET application, not as a way to install a standalone instance of Python for general use. You will likely find your Python instance easier to manage if you install Python the regular way. 

Chocolatey, a more general Windows package management system, offers Python as well. Chocolatey is a convenient way to run the Python installer and track the presence of the Python language runtime in your system — and thus a better choice than NuGet. However, it’s best to avoid mixing and matching Chocolatey installs and regular installs of Python on the same system.

Install Python on Linux the smart way

Because Linux distributions differ significantly, the typical way to install Python on Linux is to use the specific distro’s package manager. Ubuntu and Fedora, for instance, have entirely different procedures for installing Python. On Linux (and MacOS), the target directory for the install is usually predetermined and based on the Python version number, e.g., /usr/bin/python3.X on Linux, or /usr/local/opt/python/ on the Mac.

One way to avoid dealing with the intricacies of Linux package managers is to use a containerized Python runtime. Containers run isolated from the rest of the system, so you need not worry about different Python runtimes stepping on each others’ toes. However, if your workflow doesn’t already include containers, you’ll need to devote time and energy to getting up to speed with Docker. (Note that you can use containerized Python on Windows as well.)

A tool named asdf-vm also comes in handy here. You can use asdf-vm to manage multiple Python runtimes on Unix-like systems (Linux and MacOS) — and multiple runtimes for Node.js, Ruby, Elixir, and many other languages too. So if you find yourself juggling versions of other things besides Python, you’ll want to look into asdf-vm.

Install Python on MacOS the smart way

MacOS has traditionally shipped with a version of Python installed, but never more recent than Python 2.7. This created problems when Python 3 arrived, as the two versions often conflicted. The official Python documentation has some notes to this effect, but doesn’t provide any more detailed recommendations than to make sure you use the right path for the Python instance you want.

A common way to manage Python runtimes on MacOS is through the Homebrew package manager. Homebrew provides a consistent interface for downloading, installing, managing, and removing Python and other third-party command-line apps.

Install Python packages the smart way

Once you have a base install of a Python version set up, don’t start installing packages directly into it with pip — no, not even if you plan on using Python for only one project. Set up your project directories, install Python virtual environments into them, then install packages into those virtual environments. This way, the base installation stays clean.

For a high-level way to manage multiple projects with virtual environments and dependencies, look into the Poetry project. Poetry provides a command-line tool for managing virtual environments and dependencies at a high level.

Install multiple Python versions side-by-side

The single hardest issue when dealing with Python installations is how to handle different versions of Python installed side-by-side. Two universal rules of thumb apply here:

• Always install each version in a different directory.
• Ensure that any system paths are configured to point first to the version you want to run by default.

Running multiple Python versions argues strongly in favor of per-project virtual environments. When the virtual environment is activated, all Python activity within the context of the project is automatically directed towards the right version of Python, 

Another option Windows users have to control which Python version to use when multiples are installed is the py launcher app. During Python setup, you’re offered the option to install the py launcher, a small executable that lets you select (via command-line flags) which version of Python to use for a given script. For instance, to run pip for Python 3.7, you would enter py -3.7 -m pip.

Upgrade Python the smart way

Minor revision upgrades for Python — e.g., Python 3.7.2 to Python 3.7.3 — are generally easy enough. On Windows, the installer detects the presence of the existing version and upgrades it. On Linux and MacOS, the installer or package manager typically does the same thing.

However, any virtual environments you have created will also need upgrading; they don’t upgrade automatically. To upgrade Python in a virtual environment, simply navigate to the virtual environment directory and enter venv --upgrade. Again, note that this works best only for minor point revision upgrades — like Python 3.7.2 to Python 3.7.3.

If you’re performing a major point revision upgrade, such as Python 3.7 to Python 3.8, your best bet is to use venv to create a new, separate virtual environment subdirectory in the project directory, reinstall any dependencies into it, and switch to using the new virtual environment. Most IDEs with Python support (e.g., Microsoft Visual Studio Code) will detect multiple virtual environments in a project and allow you to switch between them.