A small, more complete, Python Docker image based on Alpine Linux.
Switch branches/tags
Nothing to show
Clone or download
jfloff Merge pull request #36 from kadrach/master
Install required libssl1.0 dependency.
Latest commit a171dc4 Nov 3, 2018



Docker Stars Docker Pulls Build Status

A small Python Docker image based on Alpine Linux.

Supported tags


  • onbuild images install the requirements.txt of your project from the get go. This allows you to cache your requirements right in the build. Make sure you are in the same directory of your requirements.txt file.


The default docker python images are too big, much larger than they need to be. Hence I built this simple image based on docker-alpine, that has everything needed for the most common python projects - including python-dev (which is not common in most minimal alpine python packages).

jfloff/alpine-python 2.7-slim 55MB
python 2.7-slim 138MB
jfloff/alpine-python 2.7 232MB
python 2.7-alpine 75.3MB
python 2.7 681MB
jfloff/alpine-python 3.6-slim 58.1MB
python 3.6-slim 156MB
jfloff/alpine-python 3.6 268MB
python 3.6 692MB
python 3.6-alpine 92.1MB

Perhaps this could be even smaller, but I'm not an Alpine guru. Feel free to post a PR.


  • Installs build-base and python-dev, allowing the use of more advanced packages such as gevent
  • Installs bash allowing interaction with the container
  • Just like the main python docker image, it creates useful symlinks that are expected to exist, e.g. python3 > python, pip2.7 > pip, etc.)
  • Added testing and community repositories to Alpine's /etc/apk/repositories file


This image runs python command on docker run. You can either specify your own command, e.g:

docker run --rm -ti jfloff/alpine-python python hello.py

You can also access bash inside the container:

docker run --rm -ti jfloff/alpine-python bash

Usage of onbuild images

These images can be used to bake your dependencies into an image by extending the plain python images. To do so, create a custom Dockerfile like this:

FROM jfloff/alpine-python:3.6-onbuild

# for a flask server
CMD python manage.py runserver

Don't forget to build that Dockerfile:

docker build --rm=true -t jfloff/app .

docker run --rm -t jfloff/app

Personally, I build an extended Dockerfile version (like shown above), and mount my specific application inside the container:

docker run --rm -v "$(pwd)":/home/app -w /home/app -p 5000:5000 -ti jfloff/app

Usage of slim images

These images are very small to download, and can install requirements at run-time via flags. The install only happens the first time the container is run, and dependencies can be baked in (see Creating Images).

Via docker run

These images can be run in multiple ways. With no arguments, it will run python interactively:

docker run --rm -ti jfloff/alpine-python:2.7-slim

If you specify a command, they will run that:

docker run --rm -ti jfloff/alpine-python:2.7-slim python hello.py

Pip Dependencies

Pip dependencies can be installed by the -p switch, or a requirements.txt file.

If the file is at /requirements.txt it will be automatically read for dependencies. If not, use the -P or -r switch to specify a file.

# This runs interactive Python with 'simplejson' and 'requests' installed
docker run --rm -ti jfloff/alpine-python:2.7-slim -p simplejson -p requests

# Don't forget to add '--' after your dependencies to run a custom command:
docker run --rm -ti jfloff/alpine-python:2.7-slim -p simplejson -p requests -- python hello.py

# This accomplishes the same thing by mounting a requirements.txt in:
echo 'simplejson' > requirements.txt
echo 'requests' > requirements.txt
docker run --rm -ti \
  -v requirements.txt:/requirements.txt \
  jfloff/alpine-python:2.7-slim python hello.py

# This does too, but with the file somewhere else:
echo 'simplejson requests' > myapp/requirements.txt
docker run --rm -ti \
  -v myapp:/usr/src/app \
  jfloff/alpine-python:2.7-slim \
    -r /usr/src/app/requirements.txt \
    -- python /usr/src/app/hello.py

Run-Time Dependencies

Alpine package dependencies can be installed by the -a switch, or an apk-requirements.txt file.

If the file is at /apk-requirements.txt it will be automatically read for dependencies. If not, use the -A switch to specify a file.

You can also try installing some Python modules via this method, but it is possible for Pip to interfere if it detects a version problem.

# Unknown why you'd need to do this, but you can!
docker run --rm -ti jfloff/alpine-python:2.7-slim -a openssl -- python hello.py

# This installs libxml2 module faster than via Pip, but then Pip reinstalls it because Ajenti's dependencies make it think it's the wrong version.
docker run --rm -ti jfloff/alpine-python:2.7-slim -a py-libxml2 -p ajenti

Build-Time Dependencies

Build-time Alpine package dependencies (such as compile headers) can be installed by the -b switch, or a build-requirements.txt file. They will be removed after the dependencies are installed to save space.

If the file is at /build-requirements.txt it will be automatically read for dependencies. If not, use the -B switch to specify a file.

build-base, linux-headers and python-dev are always build dependencies, you don't need to include them.

docker run --rm -ti jfloff/alpine-python:2.7-slim \
  -p gevent \
  -p libxml2 \
  -b libxslt-dev \
  -b libxml-dev \
  -- python hello.py

Creating Images

Similar to the onbuild images, dependencies can be baked into a new image by using a custom Dockerfile, e.g:

FROM jfloff/alpine-python:2.7-slim
RUN /entrypoint.sh \
  -p ajenti-panel \
  -p ajenti.plugin.dashboard \
  -p ajenti.plugin.settings \
  -p ajenti.plugin.plugins \
  -b libxml2-dev \
  -b libxslt-dev \
  -b libffi-dev \
  -b openssl-dev \
&& echo
CMD ["ajenti-panel"]
# you won't be able to add more dependencies later though-- see 'Debugging'


The /entrypoint.sh script that manages dependencies in the slim images creates an empty file, /requirements.installed, telling the script not to install any dependencies after the container's first run. Removing this file will allow the script to work again if it is needed.

You can use the -x flag to see everything the /entrypoint.sh script is doing.

You can also access bash inside the container:

docker run --rm -ti jfloff/alpine-python:2.7-slim bash

Additional Arguments

-q: silences output from /entrypoint.sh -x: turns on Bash debugging, making the output very verbose.


These are some of the images that use jfloff/alpine-python as base image. If you have another image that uses this as base image, please submit an issue or PR for it to be added. Image has to be published on Docker Hub.

  • jfloff/alscipy Docker Stars Docker Pulls : image with common packages for Science in Alpine Python.


The code in this repository, unless otherwise noted, is MIT licensed. See the LICENSE file in this repository.


At this moment with Alpine APK we are not able to install previous packages versions, i.e., its virtually impossible to provide multiple versions of Python. This is limits us to only provide the latest python3 package that's available in Alpine APK.

Ideally we would support a solution like the official python images does (see example here), where the specific Python version is downloaded and compiled. Yet, I don't want to follow the pitfall of copy-pasting that solution, otherwise we end up with almost the same image. I'm requesting PRs on this issue, either by optimizing official solution, or other.