{"id":27464,"library":"tox-docker","title":"tox-docker","description":"Manage lifecycle of Docker containers during Tox test runs. Version 5.0.0 introduces a major breaking change: tox-docker is now a plug-in installable via the pyproject.toml [tox.env_run_base] requires or as a plugin. Requires tox 4+.","status":"active","version":"5.0.0","language":"python","source_language":"en","source_url":"https://github.com/tox-dev/tox-docker","tags":["tox","docker","testing","container","plugin"],"install":[{"cmd":"pip install tox-docker","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"tox-docker 5.x requires tox >= 4.0.0 as a plugin host","package":"tox","optional":false},{"reason":"Python docker SDK (docker-py) is used for container management","package":"docker","optional":false}],"imports":[{"note":"ToxDocker is the plugin class, but typically you don't import directly; the plugin auto-registers.","wrong":"import tox_docker","symbol":"tox_docker","correct":"from tox_docker import ToxDocker"}],"quickstart":{"code":"# In pyproject.toml or tox.ini\n# pyproject.toml:\n# [tool.tox.env_run_base]\n# requires = [\"tox-docker\"]\n\n# tox.ini:\n# [tox]\n# requires = tox-docker\n# \n# [testenv]\n# deps = pytest\n# commands = pytest\n# docker = postgres:13-alpine  # optional, start containers\n\n# Then run:\n# tox","lang":"python","description":"Configure tox-docker as a plugin, then run tox. Containers defined via `docker` option in testenv are started/teardown automatically."},"warnings":[{"fix":"Upgrade tox to >=4.0.0 and follow new plugin configuration: add 'requires = tox-docker' to tox.ini or pyproject.toml.","message":"tox-docker 5.x dropped support for tox <4.0. Upgrade to tox 4+.","severity":"breaking","affected_versions":"<5.0.0"},{"fix":"If you need custom options, switch to docker-compose integration or use the container_options in configuration.","message":"The 'docker' option in testenv now expects image names only; previously you could specify complex options. Use 'docker_compose' for compose files.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Rename 'docker_compose' to 'compose' in tox.ini.","message":"The 'docker_compose' option is deprecated in 5.x and will be removed in 6.0. Use 'compose' and 'compose_project_name' instead.","severity":"deprecated","affected_versions":"5.x"},{"fix":"Define containers under a global ['docker'] section but note they are still per-environment.","message":"Containers are started for each testenv but not shared across environments. If you need shared containers, use a global docker service approach.","severity":"gotcha","affected_versions":"*"},{"fix":"Run `pip install docker` if not already installed.","message":"tox-docker 5.x requires Python 3.9+ and Docker SDK. Ensure docker-py is installed.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install tox-docker: pip install tox-docker. Also ensure you have added 'requires = tox-docker' to your tox configuration.","cause":"tox-docker is not installed or not found by tox.","error":"ModuleNotFoundError: No module named 'tox_docker'"},{"fix":"Add 'docker = postgres:13-alpine' (or another image) under the [testenv] section.","cause":"The 'docker' option is missing or incorrectly formatted.","error":"tox-docker: Error: Environment '...' does not have a 'docker' key or it is empty"},{"fix":"Ensure your tox configuration includes valid docker entries. Check for syntax errors.","cause":"Common bug when parsing docker config in tox-docker 5.0.0 with missing required fields.","error":"TypeError: argument of type 'NoneType' is not iterable"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}