Skip to main content

Kedro-Docker

Python Version PyPI version License Code Style: Black

Docker is a tool that makes it easier to create, deploy and run applications. It uses containers to package an application along with its dependencies and then runs the application in an isolated virtualised environment.

Configuring a Docker container environment may become complex and tedious. Kedro-Docker significantly simplifies this process and reduces it to 2 steps:

  1. Build a Docker image
  2. Run your Kedro project in a Docker environment

Note: Kedro-Docker also makes it easy for you to run IPython and Jupyter Notebooks in a Docker container.

How do I install Kedro-Docker?

Kedro-Docker is a Python plugin. To install it:

pip install kedro-docker

How do I use Kedro-Docker?

Prerequisites

The following conditions must be true for Kedro-Docker to package your project:

  • Make sure you have installed Docker
  • Kedro-Docker assumes that Docker daemon is up and running in your system

Generating a Dockerfile

In order to generate a Dockerfile for your project, navigate to the project's root directory and then run the following from the command line:

kedro docker init

This command will generate Dockerfile, .dockerignore and .dive-ci files for your project. Existing files are never overwritten, so you can edit them. To generate a new file, delete the old one and run kedro docker init again (kedro docker init --with-spark for a Spark project).

The generated Dockerfile is a multi-stage build:

  1. A builder stage installs the project dependencies with uv into a virtual environment at /opt/venv, from uv.lock if the project has one, otherwise from requirements.txt, otherwise from pyproject.toml
  2. A runtime stage copies only the virtual environment and the project into a clean base image, and runs kedro run as the non-root kedro_docker user

Note: kedro docker build warns you if uv.lock is out of date with pyproject.toml (when uv is installed). Run uv lock to update it.

Note: uv does not read pip.conf. To install from a private package index, configure it in [tool.uv] in pyproject.toml or in uv.toml, and pass any credentials as a build secret rather than in these files, which are copied into the image.

Build arguments, which you can pass with kedro docker build --docker-args="--build-arg NAME=value":

  • BASE_IMAGE - Python image used by every stage
  • UV_VERSION - version of uv used to install the dependencies, latest by default
  • KEDRO_UID, KEDRO_GID - user and group ID of the kedro_docker user
  • KEDRO_PIPELINES - comma-separated pipelines that the image runs by default (needs Kedro 1.2 or later), the default pipeline if empty

Options:

  • --with-spark - optional flag to create a Dockerimage file with Spark and Hadoop support
  • -h, --help - show command help and exit.

Build a Docker image

In order to build a Docker image for your project, navigate to the project's root directory and then run the following from the command line:

kedro docker build

Behind the scenes Kedro does the following:

  1. Creates a template Dockerfile and .dockerignore in the project root directory if those files don't already exist
  2. Builds the project image using the Dockerfile from the project root directory

Note: When calling kedro docker build you can also pass any specific options for docker build by specifying --docker-args option. For example, kedro docker build --docker-args="--no-cache" instructs Docker not to use cache when building the image. You can learn more about available options here.

Note: By default, kedro docker build creates an image without Spark and Hadoop.

Note: By default, when calling kedro docker build image is built with python:VERSION-slim image, where VERSION is the Python (major + minor) version from the project's .python-version file or, if there is none, from the current environment. By specifying --base-image option, different base image can be used. For example kedro docker build --base-image="python:3.12-slim".

Note: You can generate the Dockerfile, .dockerignore or .dive-ci files without building the image by running kedro docker init. This might be of use in case you would like to modify these files before the first build.

The project Docker image will automatically be tagged as <project-root-dir>:latest, where <project-root-dir> is the name of the project root directory. To change the tag, you can add the --image command line option, for example: kedro docker build --image my-project-tag.

When building the image Kedro copies the contents of the current project into the image, however it ignores the locations specified in .dockerignore file in order to prevent the propagation of potentially sensitive data into the image. We recommend mounting those volumes at runtime.

Options:

  • --uid - optional integer User ID for kedro user inside the container. Defaults to the current user's UID
  • --gid - optional integer Group ID for kedro user inside the container. Defaults to the current user's GID
  • --image - optional Docker image tag. Defaults to the project directory name
  • --docker-args - optional string containing extra options for docker build command
  • --with-spark - optional flag to create an image additionally with Spark and Hadoop
  • --base-image - optional base Docker image. Default is Debian slim with the Python version from .python-version or the current environment, e.g. python:3.12-slim
  • --pipelines - optional comma-separated pipelines that the image runs by default (needs Kedro 1.2 or later). Defaults to the default pipeline
  • -h, --help - show command help and exit.

One image per pipeline

To build an image that runs only some of the project's pipelines, use the --pipelines option:

kedro docker build --pipelines data_processing
kedro docker build --pipelines data_science

Each image is tagged <project-root-dir>-<pipelines> by default, for example my-project-data_processing, and the images share their layers. The image's default command, kedro docker run --image my-project-data_processing and kedro docker cmd --image my-project-data_processing run those pipelines. A command that calls kedro run itself, such as a Kubernetes pod spec, needs to pass --pipelines too.

Note: --pipelines needs Kedro 1.2 or later and a Dockerfile generated by Kedro-Docker 0.7.0 or later. If your project has an older one, move it and .dockerignore aside and run kedro docker init.

Note: To run other pipelines with kedro docker run, pass --pipelines to it. Choosing them in a --config file or with -e KEDRO_PIPELINES in --docker-args has no effect with kedro docker run.

Run your project in a Docker environment

Once the project image has been built, you can run the project using a Docker environment:

kedro docker run

The command above will:

  1. Locate the image built in the previous section
  2. Mount the conf/local, data, logs, notebooks, references and results directories into the /home/kedro_docker container path, where the rest of the project is already part of the image
  3. Execute kedro run command in a new container

Note: The kedro docker run command adds --rm flag to the underlying docker run call, therefore the container will be automatically removed when it exits. Please make sure that you persist all necessary data outside the container at runtime to avoid data loss.

By default kedro docker run will use an image tagged as <project-root-dir>:latest to create a container. If you renamed your image in the previous step, please also provide an --image option with the corresponding image tag, for example: kedro docker run --image "my-custom-image:latest".

When calling kedro docker run you can also pass any specific options for docker run by providing --docker-args option. Since --docker-args may contain multiple arguments, it's a good idea to add quotation marks. For example, kedro docker run --docker-args="--env KEY=MYVALUE" instructs Docker to set environment variable KEY to MYVALUE in the container. You can learn more about available options here.

All other CLI options will be appended to kedro run command inside the container. For example, kedro docker run --runner=ParallelRunner will run kedro run --runner=ParallelRunner inside the container. If the image was built with --pipelines, those pipelines are run unless you choose others, for example with kedro docker run --pipelines data_science.

Options:

  • --image - Docker image name to be used, defaults to project root directory name
  • --docker-args - optional string containing extra options for docker run command
  • -h, --help - show command help and exit
  • Any other options will be treated as kedro run command options.

Interactive development with Docker

In addition to kedro docker run Kedro also supports the following commands:

  • kedro docker ipython - Run IPython session inside the container
  • kedro docker jupyter notebook - Start a Jupyter Notebook inside the container
  • kedro docker jupyter lab - Start a Jupyter Lab inside the container

Options:

  • --image - Docker image name to be used, defaults to project root directory name
  • --docker-args - optional string containing extra options for docker run command
  • --port - host port that a container's port will be mapped to, defaults to 8888. This option applies to kedro docker jupyter commands only
  • -h, --help - show command help and exit
  • Any other options will be treated as corresponding kedro command CLI options. For example, kedro docker jupyter lab --NotebookApp.token='' --NotebookApp.password='' will run Jupyter Lab server without the password and token.

Important: Please note that source code directory of a project (src folder) is not mounted to the Docker container by default. This means that if you change any code in src directory inside the container, those changes will not be saved to the host machine and will be completely lost when the container is terminated. In order to mount the whole project when running a Jupyter Lab, for example, run the following command:

kedro docker jupyter lab --docker-args "-v ${PWD}:/home/kedro_docker"

Image analysis with Dive

Kedro-Docker allows to analyze the size efficiency of your project image by leveraging Dive:

kedro docker dive

Note: By default Kedro-Docker calls Dive in CI mode. If you want to explore your image in the UI, run kedro docker dive --no-ci.

Options:

  • --ci / --no-ci - flag for running Dive in non-interactive mode. Defaults to true
  • --ci-config-path - path to Dive CI config file. Defaults to .dive-ci in the project root directory
  • --image - Docker image name to be used, defaults to project root directory name
  • --docker-args - optional string containing extra options for docker run command
  • -h, --help - show command help and exit.

Running custom commands with Docker

You can also run an arbitrary command inside Docker container by executing kedro docker cmd <CMD>, where <CMD> corresponds to the command that you want to execute. If <CMD> is not specified, this will run the image's default command: kedro run, for the pipelines the image was built with, if any.

Note: If you are running kedro command, unlike in the previous sections, you should specify the whole command including kedro keyword. This is to allow the execution of non Kedro commands as well.

For example:

  1. kedro docker cmd kedro test will run kedro test inside the container
  2. kedro docker cmd will run kedro run inside the container
  3. kedro docker cmd --docker-args="-it" /bin/bash will create an interactive bash shell in the container (and allocate a pseudo-TTY connected to the container’s stdin).

Options:

  • --image - Docker image name to be used, defaults to project root directory name
  • --docker-args - optional string containing extra options for docker run command
  • -h, --help - show command help and exit.

Running Kedro-Docker with Kedro-Viz

These instructions allow you to access Kedro-Viz, Kedro's data pipeline visualisation tool, via Docker. In your terminal, run the following commands:

pip download -d data --no-deps kedro-viz
kedro docker build
kedro docker cmd bash --docker-args="-it -u=0 -p=4141:4141"
pip install data/*.whl
kedro viz --host=0.0.0.0 --no-browser

And then open 127.0.0.1:4141 in your preferred browser. Incidentally, if kedro-viz is already installed in the Docker container (via requirements) then you can run:

kedro docker cmd --docker-args="-p=4141:4141" kedro viz --host=0.0.0.0

Can I contribute?

Yes! Want to help build Kedro-Docker? Check out our guide to contributing.

What licence do you use?

Kedro-Docker is licensed under the Apache 2.0 License.

Python version support policy

  • The Kedro-Docker supports all Python versions that are actively maintained by the CPython core team. When a Python version reaches end of life, support for that version is dropped from kedro-docker. This is not considered a breaking change.

Metadata

Release files for kedro-docker 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kedro-docker 0.7.0
File Size Uploaded Provenance Actions
kedro_docker-0.7.0.tar.gz 27.5 kB Without provenance Details for kedro_docker-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kedro-docker 0.7.0
File Interpreter ABI Platform Actions
kedro_docker-0.7.0-py3-none-any.whl Python 3 none any Details for kedro_docker-0.7.0-py3-none-any.whl

Total release size: 47.5 kB

Release files / kedro_docker-0.7.0.tar.gz

Download URL kedro_docker-0.7.0.tar.gz
Size 27.5 kB
Tags Source
SHA-256 checksum
How to use checksums
556afbc39ad0d0df73e11d90da38f1a8b9e9d77663017e138ec6ec9787047205
BLAKE2b-256 checksum
How to use checksums
b7b9d36f0ad78c689833487092018cd302a7d75695fbe095ec6dc884437b590e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / kedro_docker-0.7.0-py3-none-any.whl

Download URL kedro_docker-0.7.0-py3-none-any.whl
Size 20.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5a4f9aaa3385e1fb9d14241c13dc1d1fd5e008faa3955d785565a6ec5d792526
BLAKE2b-256 checksum
How to use checksums
e0904b653873f448bef6b188cd824705b936196565f787d20feaaaff2c6c0948
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for kedro-docker 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page