Installation

Author

Jon Reades

Published

August 30, 2025

Over the years, we have experimented with a range of approaches to setting you up with a programming environment, and we have come to the conclusion that Podman1 is the most robust way to ensure a consistent experience. This guarantees that all students end up with the same versions of each library, that difficult-to-diagnose hardware/OS issues are minimised, and that running/recovery is the most straightforward.

Podman and Docker: How They Work

If you want to know more about the differences between Podman and Docker then you can start here. However, one way to think of Podman is as a ‘library’ of virtual computers that you can use free-of-charge. If you’d like to know more about what Podman and Docker are, and how they work, then you can read more on the Understanding Virtualisation page.

What Kind of Computer?

Many of the steps below require you to know the ‘architecture’ of your computer: are you running an ARM or Intel/AMD chipset? Are you using a 32- or 64-bit instruction sets? So please make a note of your computer’s architecture before going any further.

Apple has stopped using Intel/AMD computer chips and now uses its own ‘Apple Silicon’ (aka ‘M’) chips instead. Confusingly, these are often also referred to by their technical specification as ARM64. To find out which you have, click on the Apple icon () and select About this Mac. Look at the Processor section and you should see which type of computer you have. If you see the word Intel then you have an Intel/AMD chipset (AMD64), if you see M1, M2, M3, etc. then you have an Apple Silicon (ARM64) computer.

It is highly unlikely that you have a 32-bit machine, but every year we find one or two older machines that use this architecture. Microsoft says that you can check which kind of chip you have by doing the following:

Select ⊞ Start and then select Settings > System > About. Look at the Device specifications.

It is also unlikely that you have an ARM device if you have an off-the-shelf Windows computer. But to confirm, in the same Device specification section:

Check the System type line to see if it says “x64-based processor” (for AMD/Intel) or “ARM-based processor” (for ARM).

Downloading

Please download all of the Essential software for your computer. Installation is covered in the next section.

Installing

You can install the updated Terminal and Git/GitHub Desktop whenever you like, and you shouldn’t encounter any issues as these are quite straightforward applications. When setting up GitHub Desktop please ensure that you use your UCL email address to create the new account with GitHub.

Windows Users

Please ensure that you have updated the Windows Virtualisation Features and installed WSL2 before installing this software!

Now that you’ve downloaded Podman:

  1. Install it – usually this will mean opening the image and either dragging it your Application folder (Mac) or running the installer (Windows)
  2. Start it up – double-click the Podman icon in your Applications folder (Mac) to start the application running.

Podman Desktop

Podman Desktop

If you don’t see this window (or see lots of errors) then you may need to have a look at the ‘dealing with errors’ section.

Important

Installation on a Mac should be fairly straightforward (as evidenced by the dearth of documentation), but for Windows there is quite a bit more detail.

Configuring

Podman requires you to create a virtual machine with user-specified characteristics before you can run an image. You can think of this as specifying the ‘hardware’ of the computer before you buy it (How much RAM? How big a hard drive? And so on.). In principle, this means that you can have more than one valid configuration at a time which would allow you to tune each virtual machine to your needs (one machine could have a lot of memory, another a lot of storage).

Here’s the quick-start version:

In iTerm2 you simply type (hitting Enter after each line):

podman machine init
podman machine start

In the Windows Terminal you should be able to simply type (hitting Enter/Return after each line):

podman machine init
podman machine start
Unable to Run

In a small number of cases on Windows we’ve had error messages about permissions and been unable to start the machine that was created using init. In that case, it seems that you just need to create a new, named virtual machine (e.g. podman machine init myvm) and then change the default machine.

If you’d like to read more about fine-tuning your Podman machine we’ve got a page for that.

Testing

Copy Code to Clipboard

Whenever you see a ‘code block’ below, you will also see a ‘clipboard’ icon (Copy to Clipboard Icon) in the right. Click that, and the code will be copied to your computer’s ‘clipboard’ so that you can then paste it into the Terminal or Windows Terminal (see Base Utilities. That will save you a lot of time and effort.

To test if Podman is installed correctly, you will need to start either iTerm (macOS) or the Windows Terminal (Windows). Podman has provided a simple way to test if your installation is working correctly. You can run the following command:

podman run hello-world

Running hello-world should output something like:

Resolved "hello-world" as an alias (/etc/containers/registries.conf.d/000-shortnames.conf)
Trying to pull quay.io/podman/hello:latest...
Getting image source signatures
Copying blob sha256:1ff9adeff4443b503b304e7aa4c37bb90762947125f4a522b370162a7492ff47
Copying config sha256:83fc7ce1224f5ed3885f6aaec0bb001c0bbb2a308e3250d7408804a720c72a32
Writing manifest to image destination
!... Hello Podman World ...!

         .--"--.
       / -     - \
      / (O)   (O) \
   ~~~| -=(,Y,)=- |
    .---. /`  \   |~~
 ~/  o  o \~~~~.----. ~~
  | =(X)= |~  / (O (O) \
   ~~~~~~~  ~| =(Y_)=-  |
  ~~~~    ~~~|   U      |~~

Project:   https://github.com/containers/podman
Website:   https://podman.io
Desktop:   https://podman-desktop.io
Documents: https://docs.podman.io
YouTube:   https://youtube.com/@Podman
X/Twitter: @Podman_io
Mastodon:  @Podman_io@fosstodon.org

If you see the above messages, then Podman is installed correctly and you can move on to the next step. If you see an error message, then you will need to have a look at the problems page.

Notice how there are several things happening:

  1. Trying to pull... or Pulling from library/hello-world – this is starting the process of downloading the hello-world image from the internet.
  2. Pull complete or Writing manifest to image destination – this is telling you that it has finished downloading the image.
  3. Hello from Docker! or Hello Podman World – this is the hello-world image running and telling you that the image now running as a container.

There’s obviously a lot more to that message, but that’s the basic idea.

Running

We now need to download and run the sds2025 image that I created over the summer. The image is the ‘template’ for running containers (i.e. virtual computers) on our ‘host’ computer and it comes complete with all of the Python libraries and other tools that you’ll need to complete the module (and a good deal more besides!). Installing the image will take a while as it’s quite large (1-5GB) and so will depend on the speed of your internet connection.

You can use a single command to download and start the sds2025 container by copying the following command into the iTerm (which I’ll also call the ‘Terminal’ from here on out) or Windows Terminal (which I’m also going to start calling the ‘Terminal’ from here on out). On Windows, the below commands may work in Power Shell, but they will not work in the Command Prompt/cmd):

podman run --rm -d --name sds2025 -p 8888:8888 \
   -v "$(pwd):/home/jovyan/work" \
  jreades/sds:2025-amd start.sh jupyter lab \
  --LabApp.password='' --ServerApp.password='' --NotebookApp.token=''
podman run --rm -d --name sds2025 -p 8888:8888 \
   -v "$(pwd):/home/jovyan/work" \
  jreades/sds:2025-arm start.sh jupyter lab \
  --LabApp.password='' --ServerApp.password='' --NotebookApp.token=''
podman run --rm -d --name sds2025 -p 8888:8888 -v "$(pwd):/home/jovyan/work" jreades/sds:2025-amd start.sh jupyter lab --LabApp.password='' --ServerApp.password='' --NotebookApp.token=''
podman run --rm -d --name sds2025 -p 8888:8888 -v "$(pwd):/home/jovyan/work" jreades/sds:2025-arm start.sh jupyter lab --LabApp.password='' --ServerApp.password='' --NotebookApp.token=''
Tip

If you were using Docker instead of Podman then the command is the same except that you need to replace podman with docker. This is on purpose: open source podman is intended to replace the proprietary docker.

If you encounter any problems with the installation, please have a look at the Dealing with Problems page.

Success!

Most of you should now be able to connect to the virtual machine by pointing your browser at: localhost:8888 where you should see something like this:

Jupyter Lab Success

Jupyter Lab Success

Footnotes

  1. And Docker, which is basically the same thing.↩︎