Tutorial 0 - Let’s get set up!

Before we build our first BeeWare app, we have to make sure we’ve got all the prerequisites for running BeeWare.

Install Python

The first thing we’ll need is a working Python interpreter.

If you’re on macOS, a recent version of Python is included with Xcode or the command line developer tools. To check if you already have it, run the following command:

$ python3 --version

If Python is installed, you’ll see its version number. Otherwise, you’ll be prompted to install the command line developer tools.

You should ensure that you are using Python 3.8 or newer. If it isn’t, you’ll need to upgrade your Python install. You can get the official installer from the Python website. You can use any stable version of Python from 3.8 onward. We’d advise avoiding alphas, betas, and release candidates unless you really know what you’re doing.

Alternative Python distributions

There are lots of different ways of installing Python. You can install Python through homebrew. You can use pyenv to manage multiple Python installs on the same machine. Windows users can install Python from the Windows App Store. Users from a data science background might want to use Anaconda or Miniconda.

If you’re on macOS or Windows, it doesn’t matter how you’ve installed Python - it only matters that you can run python3 from your operating system’s command prompt/terminal application, and get a working Python interpreter.

If you’re on Linux, you must use the system Python provided by your operating system. You will be able to complete most of this tutorial using a non-system Python, but you won’t be able to package your application for distribution to others.

Install dependencies

Next, install the additional dependencies needed for your operating system:

Building BeeWare apps on macOS requires:

  • Git, a version control system. This is included with Xcode or the command line developer tools, which you installed above. You may need to open Xcode for the first time in order for Git to work in your terminal session. If it still doesn’t register that Git is installed, you may need to restart your terminal session.

Set up a virtual environment

We’re now going to create a virtual environment - a “sandbox” that we can use to isolate our work on this tutorial from our main Python installation. If we install packages into the virtual environment, our main Python installation (and any other Python projects on our computer) won’t be affected. If we make a complete mess of our virtual environment, we’ll be able to simply delete it and start again, without affecting any other Python project on our computer, and without the need to re-install Python.

$ mkdir beeware-tutorial
$ cd beeware-tutorial
$ python3 -m venv beeware-venv
$ source beeware-venv/bin/activate

If this worked, your prompt should now be changed - it should have a (beeware-venv) prefix. This lets you know that you’re currently in your BeeWare virtual environment. Whenever you’re working on this tutorial, you should make sure your virtual environment is activated. If it isn’t, re-run the last command (the activate command) to re-activate your environment.

Alternative virtual environments

If you’re using Anaconda or miniconda, you may be more familiar with using conda environments. You might also have heard of virtualenv, a predecessor to Python’s built in venv module. As with Python installs - if you’re on macOS or Windows, it doesn’t matter how you create your virtual environment, as long as you have one. If you’re on Linux, you should stick to venv and the system Python.

Next steps

We’ve now set up our environment. We’re ready to create our first BeeWare application.