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 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 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 /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 ln -s is the Linux command to create a symbolic link ln -s is the Linux command to create a symbolic link ln -s /usr/bin/pip3 is the source - the actual executable for pip3 (Python 3's package manager) /usr/bin/pip3 is the source - the actual executable for pip3 (Python 3's package manager) /usr/bin/pip3 /usr/bin/pip is the destination - the new symlink being created /usr/bin/pip is the destination - the new symlink being created /usr/bin/pip 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. pip pip3 pip pip3 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. pip pip3 pip install requests 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 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.

This story contains new, firsthand information uncovered by the writer.

The code in this story is for educational purposes. The readers are solely responsible for whatever they build with it.

Hallucinations by Design (Part 2): The Silent Flaws of Embeddings & Why Your AI Is Getting It Wrong

Hallucination by Design: How Embedding Models Misunderstand Language 

Books authored by me

Microsoft BUILD Session

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

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Embeddings 101: Unlocking Semantic Relationships in Text

Optimizing Docker Images is More Than Just a One and Done Thing

Embeddings 101: Unlocking Semantic Relationships in Text

Optimizing Docker Images is More Than Just a One and Done Thing

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps