I love Python. And Python’s ecosystem is great. But starting Python can be rocky. So here’s some random miscellaneous tips I remember getting people set up.
In general, The Hitchhiker’s Guide to Python is a great resource.
- Use Python 3.8, 3.7, or 3.6 if you must. Don’t use anything below 3.6
- Know what PyPI is
- Always use virtual environments…
- … but you don’t need to install
virtualenv, as Python 3 has
- Also, there are other options of managing virtual environments, like
- Consider setting
- Consider using poetry, but only if you like it and it makes sense to you. It’s completely fine not to use it, too
- Django is great, but very complex. Unless you know you’ll need the features Django offers, it’s easier to start with Flask
Use a recent Python 3 version
Python 2 is dead. If you start off with Python 2 now, you are setting yourself up for a hard time in the future. Give yourself a fighting chance and use Python 3.
Many systems still come with Python 2, this is okay. You can run both Python 2
and Python 3. To check if you have Python 3 installed, you can usually just
check if you have an executable called
Although you may need to check specific versions like
python3.6. These binary names are codified in the Python Enhancement
Proposal (PEP 394), although of
course Windows doesn’t behave. In
general, using Windows will be more painful.
Python 3.8 is very stable. Don’t run anything below 3.6, and newer is better. You’ll miss out on some neat, new features that can make life easier if you aren’t running 3.7 or 3.8.
A quick note on PyPI
The Python Package Index, or PyPI for short, is where you can easily download packages to use in your project. We’ll go over the tools that make this easy, but you should know what PyPI is.
Understanding virtual environments
I wish I didn’t have to explain this, but virtual environments are pretty much required in practice, so here we go. Stick with me.
Why do I need a virtual environment?
In theory, it should be as simple as
pip install <cool-library>. But will this
use Python 2 or Python 3? If you’re clever, you might try and use
<cool-library> (if your system provides this command). This is only slightly better.
pip installs packages into your global, system-wide Python
installation. But this can very easily break other installed stuff. Fixing this
is a major headache; it isn’t worth it.
To be fair, Python does have a good solution - a virtual environment aka. virtualenv. There require a bit more setup, but are totally worth it.
Virtual environments set up a separate environment that keeps stuff away from your global Python installation, and is easy to wipe away. This means it’s no big deal if stuff gets messed up.
virtualenv and venv
TL;DR: Don’t install
virtualenv, e.g. via
pip install virtualenv. Use
There is an old package that is called
virtualenv, but in Python 3, it’s
unnecessary to install. Python 3 comes with it’s own virtualenv utility, which
works fine. Although on e.g. Ubuntu, for some dumb reason, you’ll have to
install that via
This is how you create a virtual environment:
python3 -m venv env
env is actually what the directory containing the virtualenv will be
called. Idiomatically, it’s usually called
Pick one of these, many tools will auto-detect them (like that default Python
.gitignore, or IDEs). I’m going to assume you called it
env, which I picked
because it’s a bit less confusing than two
Unfortunately, before you can use the virtualenv, you have to “activate” it.
This basically sets things like
pip to point to the virtualenv
versions. For e.g. bash, you do this by typing:
Once activated, your shell usually displays some kind of indication it’s active,
e.g. by showing
(env) in the prompt:
$ which python /usr/bin/python $ python3 -m venv env $ source env/bin/activate (env) $ which python /home/me/env/bin/python
If you close your terminal, or open a new window or tab, you’ll have to re-activate the virtualenv. Also, if you use an IDE, you’ll have to set it to use the virtualenv, too. Here’s how to do that in PyCharm and VSCode. I believe PyCharm can also create a virtualenv for you.
Finally, consider setting
true. With bash, you’d
add this to your
The Hitchhiker’s Guide to Python has more options on how to set this up on e.g. Windows.
As the name suggests, this will save you from accidentally running
without a virtualenv activated, and so prevent you from messing up the system
installation. It has saved me many times.
To allow other people to create a virtualenv to match yours, the common way of
doing this is using a file called
requirements.txt. You put your requirements
in that, and then someone else can install them all at once using:
pip install -r requirements.txt
In it’s simplest form, it’s just one line per package you’d install via
install, so for example:
To install those two packages. It can be more complex, for example you can also
specify which versions are needed, e.g. if you depend on a minimum version.
requirements.txt file from the start is a good idea, but also
tedious (although maybe less tedious than figuring it out later).
Alternatives to venv (pipenv, poetry)
These alternatives make managing a virtualenv easier, but also bring more
complexity. I believe understanding
venv is important, and hiding it only
hurts Python beginners in the long run. It’s an important part of Python, even
if it is unfortunate. That said, managing virtualenvs and requirements is tedious.
The author of “The Hitchhiker’s Guide to Python” also wrote
explains why he pushes it so hard. This post isn’t the place to go into detail,
but there’s controversy around
pipenv. Apart from the controversy - which is
also tedious - the reason I don’t like
pipenv is mundane: you can’t specify
Python 3.x or
you have to pick exactly one. For some scenarios, this is fine, but it can also
turn into a hassle if you want to share your code.
TL;DR: I would avoid
Poetry is a fairly new project, but does everything right - for me.
It’s easy to set up, this will create a new folder for you project:
poetry new <project>
Alternatively, you can use
poetry init for existing projects.
It makes managing requirements easy. You just run this command, and it keeps
track of them for you - no more manually updating
poetry add <cool-library>
It also can keep track of development dependencies, like unit test libraries.
Usually, this is a right pain requiring a second requirements file, often called
requirements-dev.txt, but with poetry, it’s simply:
poetry add --dev pytest
Installing the virtualenv is also easy:
This is also what other people can run when they download your project. Activating the virtualenv is also easy:
As I said, poetry is fairly new, and you’ll have to get used to some terminology
being different. You no longer need to manually make a virtualenv, the
pyproject.toml file replaces
But poetry does simplify workflows, including building artefacts or publishing
your project to PyPI. I’m 100% happy with it, and can easily recommend it, even
Django is a great - if not the greatest - web framework, with loads of features. But it crushes even advanced Python users with a lot of complexity and Django-specific knowledge. Unless you are using Django in a professional (i.e. paid), customer-facing project, or you know you absolutely need many of the features Django offers, other options are available.
Flask is also great, but very different. It’s a “micro”-framework, so the way you get more features is by using add-ons. This means it’s relatively simple, although you’ll have to slowly add things, and not all add-ons are as good. But it grows with you, and the templating engine is easily the best there is.
Flask makes projects fun, and so increases your change of success. I have written many an internal tool in Flask. It’s quick to get started, quick to get working, and quick to deploy. It’s a real joy. Flask is surprisingly capable.
And should you need to, it isn’t too horrible to port Flask projects to Django. They share a lot of DNA. I’m not going to pretend it’s easy. But getting a proof of concept running in Flask is a lot easier, and a trade-off I would make. If you ever find yourself in the situation of having to port to Django, that’s a success already in my books. Make no mistake, Flask is very capable and shouldn’t be seen as less professional. But there’s no denying Django offers more for e.g. big e-commerce projects, or when you need some CRM aspects for business reasons.
I hope this helps you get started with Python, or helps you tame some Python projects you had lying around!