What's the difference between the various ways of importing stuff in Python? Should you import the whole module or use from? How about that one that everyone tells you never to use?

Let's see how you can understand the types of import using three pictures. Yep—that's it. Oh well, I'll write some short notes, but this tutorial pretty much only consists of three pictures. (After the very long pair of articles I published last time, you'll be pleased to get through this one quickly.)

import some_module

One option is to import the whole module:

Here's what this looks like:

You import the whole module—the box labelled some_module in this picture—and you place it on the "shelf" in your program.

The box contains stuff—the various functions, classes, and variable names the module contains.

But when you need something from the box, you need to refer to the box first since that's where you can find its contents:

This line fetches the hat from the some_module box. You can fetch anything that's in the box.

from some_module import hat

If all you want is the hat, you could use the following import statement:

Now you only fetch the hat from the box, and the hat is the only thing you put on the program's shelf:

When you need the hat in your program, you can simply write:

Simple. But that's the only item you have access to. You can't use anything else from the box as you only placed one item on the program's shelf, not the whole box.

from some_module import *

Horror! This is ill-advised in almost all cases. Don't do it. But it's valid Python code:

The * is the wildcard in this case, which means you import everything from some_module.

But why shouldn't you do this? Isn't this similar to the first version, where you have access to everything?

No. Here's why:

You dump everything from the box directly on the shelf. The items are no longer neatly stored in a clearly-labelled box. Instead they're all in a heap on the shelf.

If you want to access these items, you can do so directly:

But what if you have another box (module) that has a different pencil and another hat? What would your program fetch when you write hat? [Answer: The last one that was imported, but you're asking for trouble!]

Final Words

The difference between the three is best understood through Python's namespaces. When you import the whole module, such as import some_module, the name some_module is part of the program's main namespace. However, the module's contents aren't. They're in the module's namespace. That's why you need to access them using some_module.hat.

But when you use the from keyword to import, you don't import the whole module. Therefore, there's no module namespace. Instead, you place whatever you import directly into the main program's namespace alongside any other name that exists there, such as variable names and functions you define directly in your main program.

It's fine to do so in certain cases when you only need one or a few names from the module. However, importing from the module using the wildcard litters the main namespace with lots of names you'll never use and that can lead to conflicts with other objects with the same name.

The Zen of Python ends with this:

Namespaces are one honking great idea -- let's do more of those!

Right, I promised to be brief today. See you next time.

Code in this article uses Python 3.13

The code images used in this article are created using Snappify. [Affiliate link]

The Python Coding Stack is free. All articles are free forever. But if you enjoy these articles and find them useful, and if you’re in a position to do so, you can become a paid subscriber to help support this publication.

You can also make a one-off contribution of any amount you wish.

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

And you can find out more about me at stephengruppetta.com

Further reading related to this article’s topic:

• I discussed a different problem that can occur with imports in this narrative article: The Code That Almost Led to Disaster • A Starbase Story

• And for a much more detailed read: Python import: Advanced Techniques and Tips – Real Python

• The boxes and shelves are a small part of a broader analogy I use to explain Python programs. You can read the full analogy in this multi-part series: Monty and The White Room Analogy