Docker commands Guide – docker import with examples

Here’s a complete tutorial on docker import, covering what it does, examples, and use cases.

What is docker import?

docker import is a Docker command that creates a new image from a tarball containing a container’s filesystem. It is often used to restore containers from exported tar files or to create custom images from minimal filesystems.

Key Features:

• Converts a tarball (container snapshot) into a new Docker image.
• Restores backup tarballs created with docker export.
• Allows for custom image creation from external filesystems.
• Supports adding tags and metadata during the import process.

Basic Syntax

docker import [OPTIONS] file|URL|- [REPOSITORY[:TAG]]
Code language: JavaScript (javascript)

Options:

• -c, --change: Apply Dockerfile instructions (e.g., CMD, ENV) to the image during import.
• -m, --message: Add a commit message to the new image.

Examples of docker import

1. Import a Tarball as a New Image

docker import my_container.tar my_new_image:latest
Code language: CSS (css)

This creates a new image called my_new_image:latest from the tarball my_container.tar.

2. Import a Tarball with a Commit Message

docker import -m "Restored from backup" my_container.tar restored_image:backup
Code language: JavaScript (javascript)

This imports the tarball and adds a message describing the image.

3. Apply Dockerfile Instructions During Import

docker import -c "CMD /bin/bash" my_container.tar custom_image:1.0
Code language: JavaScript (javascript)

This sets the default command (CMD) for the new image to /bin/bash.

4. Import from a Remote URL

docker import https://example.com/container_backup.tar my_remote_image:latest
Code language: JavaScript (javascript)

This imports an image directly from a remote tarball URL.

5. Import and Set Multiple Instructions

docker import -c "ENV APP_ENV=production" -c "CMD /start.sh" my_backup.tar production_image:1.0
Code language: JavaScript (javascript)

This sets an environment variable (APP_ENV) and a startup command (/start.sh).

6. Import a Tarball Using Standard Input

cat my_container.tar | docker import - custom_image:latest
Code language: JavaScript (javascript)

This reads the tarball from standard input and creates a new image.

7. Rebuild a Base Image

docker import minimal_rootfs.tar minimal_image:latest
Code language: CSS (css)

This creates a minimal image from a tarball containing a custom Linux filesystem (minimal_rootfs.tar).

8. Restore an Exported Container

Export the container:

docker export my_container -o my_container.tar
Code language: JavaScript (javascript)

Import the tarball as a new image:

docker import my_container.tar restored_image:latest
Code language: CSS (css)

9. Automate Import with a Script

#!/bin/bash
docker import -c "CMD /bin/bash" /backups/my_container.tar backup_image:$(date +%Y%m%d)
echo "Image imported with tag backup_image:$(date +%Y%m%d)"
Code language: JavaScript (javascript)

Use Cases for docker import

1. Restoring Containers from Backups

• Use docker import to restore a container’s filesystem from a backup tarball.
• Example: Recover a database container from a previously exported snapshot.

2. Creating Minimal Base Images

• Build custom base images by importing minimal filesystems (e.g., custom Alpine, Ubuntu).
• Example: Create a stripped-down Linux image from a root filesystem tarball.

3. Custom Image Creation

• Import tarballs with pre-installed software or configurations and turn them into reusable images.
• Example: Import a tarball containing an application and its dependencies.

4. Transferring Containers Between Systems

• Use docker export and docker import to move containers between environments.
• Example: Transfer a container from a development machine to a production server.

5. Integrating with Legacy Systems

• Import filesystems from non-Docker environments to create Docker images.
• Example: Convert a physical server’s filesystem into a Docker image.

6. Simplifying CI/CD Pipelines

• Pre-build images with specific dependencies and import them in CI/CD pipelines.

List of Common docker import Commands

Best Practices for Using docker import:

1. Use docker import for restoring containers or creating custom base images—not for everyday image builds (prefer Dockerfiles for reproducibility).
2. Combine with docker export for seamless backup and restore processes.
3. Add Dockerfile instructions (--change) to set environment variables, commands, or default entrypoints.
4. Use meaningful tags to track imported images (e.g., backup:20260207).
5. Verify the imported image by running it and inspecting its configuration (docker inspect).

Common Errors and Solutions

1. “No such file or directory”
   → Ensure the tarball exists and the path is correct.
2. “Permission denied”
   → Check permissions on the tarball or run the command with sudo.
3. “Invalid tar file”
   → Verify that the tarball is properly created and contains the correct filesystem structure.
4. “Imported image does not start correctly”
   → Use -c to set the CMD or ENTRYPOINT during import.

Combining docker import with Other Commands

Export and Re-Import for Backup and Restore

Export the container:

docker export my_container -o my_container.tar
Code language: JavaScript (javascript)

Re-import it as a new image:

docker import my_container.tar my_restored_image:latest
docker run -it my_restored_image bash
Code language: CSS (css)

Build a Custom Base Image

docker import custom_rootfs.tar my_base_image:1.0
Code language: CSS (css)

Check the Imported Image

docker inspect my_base_image:1.0
docker run -it my_base_image:1.0 bash
Code language: CSS (css)

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.