Resolving Docker-Compose TypeError with 'ssl_version' in GitLab

Problem Statement

When running Docker commands in GitLab CI/CD pipelines, users encounter the following error after a recent update:

TypeError: kwargs_from_env() got an unexpected keyword argument 'ssl_version'

This error occurs during the docker_test pipeline stage using the docker:stable-dind service. The failure often appears suddenly despite no configuration changes, breaking existing workflows that previously worked.

Root Cause

The error stems from a breaking change in docker-py (Python Docker client library) version 7.0.0:

1. The kwargs_from_env() method no longer accepts ssl_version arguments
2. This impacts Docker Compose v1 installed via Python (docker-compose)
3. Docker has officially replaced the Python-based Compose v1 with Go-based Compose v2

Permanent Solution: Migrate to Docker Compose v2

Why Migrate?

• Compose v1 is deprecated and unsupported
• Compose v2 offers better performance and integration
• Maintains compatibility with future Docker versions
• Included out-of-the-box with recent Docker installations

Official Reference

Docker Compose Migration Documentation

Migration Steps

1. Update GitLab CI configuration to use compatible Docker versions:

docker_test:
  image: docker:20.10.24
  services:
    - docker:20.10.24-dind
  stage: docker-test

2. Replace all docker-compose commands in your scripts with docker compose:

- docker-compose up -d
+ docker compose up -d

3. Remove deprecated flags (Compose v2 automatically manages configuration):

- docker-compose -f docker-compose.prod.yml build
+ docker compose build

Key Differences

Compose v1 (docker-compose)	Compose v2 (docker compose)
Separate Python binary	Integrated Docker subcommand
Hyphen syntax (docker-compose)	Space syntax (docker compose)
Manual installation required	Bundled with Docker Engine

Temporary Workaround: Downgrade Docker-Py

If immediate migration isn't feasible, downgrade the Python Docker client:

pip uninstall -y docker
pip install docker==6.1.3

Critical Notes

1. This is a short-term solution only
2. Downgrading leaves known vulnerabilities unpatched
3. Version 6.1.3 lacks security updates and new features
4. Schedule migration to v2 at earliest opportunity

Solutions to Avoid

1. Modifying Docker Python Internals

# Avoid this hack to re-add ssl_version
def kwargs_from_env(environment=None, ssl_version=None): ...

• Why it's risky: Bypasses security improvements, creates inconsistent environments
• Potential impacts: Breaks future upgrades, voids support options

2. Installing Outdated Docker Containers

• Older docker:latest images cause compatibility issues
• May introduce undocumented bugs and security gaps
• Lacks Compose v2 support

Best Practices for GitLab CI/CD

stages:
  - docker-test

docker_test:
  variables:
    DOCKER_HOST: tcp://docker:2376
    DOCKER_TLS_VERIFY: '1'
  image: docker:20.10.24
  services:
    - name: docker:20.10.24-dind
      alias: docker
  script:
    - docker compose version
    - docker compose up -d --build

Key configuration notes:

• Pin specific version tags (20.10.24 instead of stable)
• Always configure DOCKER_HOST and TLS verification
• Verify Compose v2 with docker compose version
• Avoid docker-compose legacy commands

Conclusion

1. Recommended solution: Migrate to Docker Compose v2 using docker compose commands

   • Update CI images to Docker >=20.10.24
   • Replace hyphentated docker-compose calls

2. Temporary mitigation: Install docker==6.1.3 if migration requires more time

   • Set explicit timeline for full migration
   • Monitor for dependency conflicts

3. Avoid: Dangerous workarounds like modifying Docker internals or using outdated base images

Verification Step

Confirm successful migration:

docker compose version
# Docker Compose version v2.20.3

Complete your migration following the official guide for handling syntax differences between v1 and v2 implementations.