Python in Docker: The Tiny Fix That Saves Hours of Headaches

One Line of Code, Zero Container Crashes: The Python Alias Magic

Ever spent time debugging why your Docker container suddenly can’t find Python? I have, and it’s not fun. When I first started containerizing Python apps, I hit this problem constantly. Let me tell you how a simple alias can save you from this frustration.

The Problem We All Face

So there I was, building a nice clean Docker image for my Flask app. The code worked perfectly on my machine (doesn’t it always?). I’d written a beautiful Dockerfile, pushed it to our repo, and felt pretty good about myself.

Then my teammate tried to run it.

“Your container keeps crashing,” she messaged. “Something about Python not found.”

I couldn’t believe it. Everything was there — I’d installed python3, all the dependencies… wait.

That was it. I’d installed python3, but my scripts were calling python.

CLASSIC MISTAKE

Why This Happens

This problem is super common. Most modern Linux distros (and our Docker images) come with Python 3 installed as python3, not python. But tons of scripts, build tools, and developers are still in the habit of typing just “python”.

It’s this small but critical disconnect that causes builds to fail, deployment pipelines to break, and developers to waste hours troubleshooting.

The Simple Fix

Here’s the solution I wish someone had told me earlier:

FROM ubuntu:22.04

# Install Python 3
RUN apt-get update && apt-get install -y python3 python3-pip

# Create the alias with a symlink
RUN ln -s /usr/bin/python3 /usr/bin/python

# You might want this too
RUN ln -s /usr/bin/pip3 /usr/bin/pip

This command creates a symbolic link (symlink) in your Docker container.

ln -s /usr/bin/pip3 /usr/bin/pip

• ln -s is the Linux command to create a symbolic link

• /usr/bin/pip3 is the source - the actual executable for pip3 (Python 3's package manager)

• /usr/bin/pip is the destination - the new symlink being created

  
  

When you run this command in your Dockerfile, it essentially creates a shortcut called pip that points to the pip3 executable. This means that whenever something in your container tries to run pip, it will actually run pip3 instead.

This is particularly useful because many scripts, tutorials, and developers are accustomed to typing just pip rather than pip3, even when working with Python 3. With this symlink in place, commands like pip install requests will work correctly in your container even though the actual executable is pip3.

It’s a simple but effective way to maintain compatibility with existing code and workflows while using Python 3 in your Docker container.

But wait, Why not use an alias

You might wonder why we don’t just use a shell alias like:

RUN echo 'alias python=python3' >> /etc/bash.bashrc

I tried that first. It works… sometimes. The problem is that shell aliases only work in interactive shells. Scripts, Makefiles, and other automated processes won’t see your alias.

The symlink approach works everywhere, with everything. It’s more reliable and doesn’t depend on which shell you’re using.

The Big Picture

This tiny fix has saved me countless hours of debugging. Now it’s part of every Python Dockerfile I write.

And there’s a lesson here. Sometimes it’s these small compatibility issues — not complex architectural problems — that cause the biggest headaches in software development. The best solutions are often simple, but not always obvious until you’ve banged your head against the wall a few times.

What’s your go-to Docker trick? I’d love to hear what small changes have made your container builds more reliable.