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.

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:

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.

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.

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:

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.

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.

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.

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.

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:

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.

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.

This story, "How to install Python the smart way" was originally published by InfoWorld.