{"id":4935,"library":"dockerpty","title":"dockerpty: Pseudo-TTY handler for Docker Python client","description":"dockerpty is a Python library that provides functionality to operate the pseudo-tty (PTY) allocated to a Docker container, using the Python client. It enables bridging the input and output streams of a Docker container's terminal with the host's terminal, allowing for interactive shell sessions within containers. The library's last release was in February 2016.","status":"maintenance","version":"0.4.1","language":"en","source_language":"en","source_url":"https://github.com/d11wtq/dockerpty","tags":["docker","pty","terminal","container","devops","interactive"],"install":[{"cmd":"pip install dockerpty","lang":"bash","label":"Install dockerpty"}],"dependencies":[{"reason":"dockerpty relies on the older `docker-py` client library (>=0.3.2) for Docker API interaction. It is not compatible with newer versions of the `docker` (Docker SDK for Python) library. Users must explicitly install `docker-py` alongside `dockerpty` if they intend to use it.","package":"docker-py","optional":false}],"imports":[{"note":"Primary import for using the library's `start()` function.","symbol":"dockerpty","correct":"import dockerpty"},{"note":"Used for more explicit object-oriented control over the PTY, as shown in some examples.","symbol":"PseudoTerminal","correct":"from dockerpty import PseudoTerminal"}],"quickstart":{"code":"import docker\nimport dockerpty\nimport os\n\n# Ensure docker-py is installed: pip install docker-py\n# This example uses the older docker-py client API.\n# For modern Docker SDK for Python, direct use of `attach()` or `exec_run()` might be preferred.\n\n# For demonstration, ensure a Docker daemon is running.\n# For this example to be interactive, run it in a terminal.\n\ntry:\n    # Using the older docker.Client() from docker-py\n    # Modern Docker SDK uses docker.from_env() or docker.DockerClient()\n    # For this example to work with docker-py, install it:\n    # pip install docker-py\n    client = docker.Client(base_url=os.environ.get('DOCKER_HOST', 'unix://var/run/docker.sock'))\n\n    # Create a container with TTY and stdin_open for interactive use\n    container = client.create_container(\n        image='busybox:latest',\n        stdin_open=True,\n        tty=True,\n        command='/bin/sh',\n    )\n    print(f\"Container created with ID: {container['Id']}\")\n\n    # Start the container\n    client.start(container)\n\n    print(\"Attaching to container's PTY. Type 'exit' to quit the shell and container.\")\n    # Attach to the container's pseudo-terminal\n    # Passing logs=1 is recommended due to an internal DeprecationWarning in dockerpty 0.4.1\n    dockerpty.start(client, container, logs=1)\n\n    print(f\"Container {container['Id']} exited.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure Docker daemon is running and `docker-py` is installed (not just `docker` SDK). \")\n    print(\"This library is designed for an older Docker client version.\")\nfinally:\n    # Clean up the container\n    if 'container' in locals() and client:\n        try:\n            client.remove_container(container, v=True, force=True)\n            print(f\"Container {container['Id']} removed.\")\n        except Exception as e:\n            print(f\"Error removing container: {e}\")\n","lang":"python","description":"This example demonstrates how to create and attach to an interactive shell within a Docker container using `dockerpty`. It uses the `docker.Client()` class from the older `docker-py` library to interact with the Docker daemon. The container is created with `stdin_open=True` and `tty=True` to enable interactive terminal functionality. The `dockerpty.start()` function then takes control of the current terminal, piping its input/output to/from the container's PTY."},"warnings":[{"fix":"Use the `docker-py` library (e.g., `pip install docker-py==1.10.6`) instead of the `docker` (Docker SDK for Python) library when using `dockerpty`. For new projects, consider using the native `attach()` or `exec_run()` methods provided by the modern Docker SDK for Python as alternatives to `dockerpty`.","message":"dockerpty (v0.4.1) is incompatible with Docker SDK for Python (package `docker`) versions 2.0 and above. It relies on the `client.inspect_container()` method, which was moved to `APIClient.inspect_container()` in `docker` SDK v2.0, causing `AttributeError`.","severity":"breaking","affected_versions":"dockerpty<=0.4.1 used with docker>=2.0"},{"fix":"For new development, explore the `attach()` and `exec_run()` methods of the official `docker` SDK for Python. If `dockerpty`'s specific features are required, be aware of its unmaintained status and dependency on older Docker client versions.","message":"The `dockerpty` library has not been updated since February 2016 (version 0.4.1). It relies on the now-deprecated `docker-py` library. For modern Python applications, it's generally recommended to use the official Docker SDK for Python (`pip install docker`) and its built-in functionalities like `container.attach()` or `container.exec_run()` for interactive container sessions.","severity":"deprecated","affected_versions":"All versions of dockerpty"},{"fix":"Always ensure `stdin_open=True` and `tty=True` are passed to `client.create_container()` when intending to use `dockerpty` for interactive PTY sessions.","message":"For full interactive terminal control, the Docker container must be created with `stdin_open=True` and `tty=True`. If these flags are not set, `dockerpty` can still stream container output but will not provide interactive input or pseudo-terminal resizing.","severity":"gotcha","affected_versions":"All versions of dockerpty"},{"fix":"Be aware of this key sequence if you intend to gracefully detach from an interactive container without stopping it. To stop the container, typically type 'exit' into the container's shell.","message":"The key sequence `C-p C-q` (Ctrl+p then Ctrl+q) will detach from the container's pseudo-terminal, leaving the container running in the background. This is standard Docker behavior for detaching from an attached container.","severity":"gotcha","affected_versions":"All versions of dockerpty"},{"fix":"Pass `logs=1` as a keyword argument to `dockerpty.start()`: `dockerpty.start(client, container, logs=1)`.","message":"An internal `DeprecationWarning` exists within `dockerpty/pty.py` (v0.4.1) indicating that a future version will require the `logs=1` argument in `dockerpty.start()` to maintain current behavior. While `dockerpty` has not seen new releases, it's a good practice to include `logs=1` when calling `dockerpty.start()` to avoid potential issues or warnings from the library itself.","severity":"deprecated","affected_versions":"dockerpty==0.4.1"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}