Easy Docker Manager

Easy Docker Manager (EDM) lets you inspect local Docker containers from a keyboard-driven terminal interface. It uses Urwid for the screen and the Docker Python SDK to read container data.

With EDM, you can view:

• a list of running containers
• recent logs with automatic updates
• container environment variables
• a readable summary of Docker inspection data
• the process list returned by Docker top
• live filtering and sorting of the running-container list
• a separate search query for each container tab
• export of the active tab to a local text file
• a local JSON configuration file

Demo

Requirements

• Python 3.9 or newer
• Docker installed and running
• permission to access the local Docker daemon
• a terminal window of at least 120 columns by 30 rows

EDM currently supports local Docker only. It accepts the platform's default local connection, Unix sockets, and Windows named pipes. A DOCKER_HOST value using a remote transport such as TCP or SSH is rejected.

[!WARNING] EDM needs access to the local Docker daemon. This is highly privileged access. On Linux, membership in the docker group grants root-level privileges. Give Docker access only to trusted users, and never make the Docker socket world-writable. See Docker's Linux post-installation guidance for supported access options.

Installation

For normal use, install EDM with pipx:

pipx install easy-docker-manager

pipx keeps EDM in its own environment and makes the edm command available from your terminal.

You can also install EDM with pip. Using a virtual environment keeps it separate from other Python packages:

python -m venv .venv

Activate the environment on Linux or macOS:

source .venv/bin/activate

Activate it in Windows PowerShell:

.venv\Scripts\Activate.ps1

Or activate it in Windows Command Prompt:

.venv\Scripts\activate.bat

Then install the package from PyPI:

python -m pip install easy-docker-manager

For work on the source code, follow the development setup.

Running EDM

Run the installed command:

edm

EDM checks the terminal size before it starts. If the window is smaller than 120 columns by 30 rows, EDM prints the current size and exits. Resize the terminal and run the command again.

Show the available command options or installed version, or start EDM without terminal colors:

edm --help
edm --version
edm --no-color

You can also run the Python module directly:

python -m easy_docker_manager

Keyboard Controls

While entering a search, press Enter to keep the query and return to detail navigation. Press Esc to keep the query and return to the container list.

Container Filtering

Press f while the container panel is active, then type part of a container name, image name, or status. Matching ignores letter case and updates the list as you type. It uses the container data already loaded in EDM and does not send another request to Docker.

* localhost (active)
────────────────────────
 f  Filter: off
 s  Sort: Docker order
────────────────────────
> container-one (running)
  container-two (running)

Use Backspace to remove the last character. Press Enter to keep the edited filter, or press Esc to restore the filter that was active before you pressed f. Other navigation and shortcut keys are disabled until editing ends. Every printable key, including q, becomes part of the query.

The filter and match count are shown below localhost (active), next to the f shortcut. The active sort appears on the next line beside s. EDM applies the selected sort before the filter and reapplies both after each container-list refresh. If the selected container no longer matches, the first matching container is selected. Filtering only hides list entries; cached tab data for hidden running containers is kept.

Container Sorting

Press s while the container panel is active to open this menu:

Sort Containers

  Docker order
> Name
  Image
  Status
  Creation time

Direction: Ascending

Up/Down Field   Left/Right Direction
Enter Apply     Esc Cancel

Use Up and Down to choose a field. Use Left for ascending order and Right for descending order. Enter applies the choice, while Esc closes the menu without changing the list. The active sort is shown above the container list, directly below the active filter.

Applying a sort does not change the selected container. The sort stays active after the container list refreshes. Choose Docker order to restore the order returned by Docker.

EDM currently shows running containers only, so they usually have the same status. For this reason, sorting by Status may not visibly change the list.

Exporting Tab Content

Press e while the detail panel is active to export the selected container's Logs, Env, Config, or Top tab. The popup lets you edit the destination path and choose one of these scopes:

• Current view exports the lines currently shown after a Logs filter. Env, Config, and Top searches highlight text without hiding lines, so their current view contains all loaded text.
• Full loaded tab exports all text currently held in EDM's cache. It does not request more data or older logs from Docker.

The suggested path starts in the directory where you launched EDM. Logs use a .log extension; the other tabs use .txt. Relative paths are also resolved from that launch directory. When the path is inside your home directory, the File field shows the home directory as ~ to keep the path shorter.

While File is selected, printable keys, including q and Q, edit the path. Use Left and Right to move its cursor, Home or End to jump to either end, and Backspace or Delete to remove characters. Use Up, Down, or Tab to move between File and Scope.

Exports may contain passwords, tokens, URLs, command arguments, or other sensitive values. EDM shows a warning before every export and writes the text without hiding values. Review exported files before sharing them. EDM never replaces an existing file without asking for confirmation.

Detail Tabs

Each container and tab keeps its own search query:

• Logs treats the query as a case-insensitive regular expression and hides lines that do not match.
• Env, Config, and Top use case-insensitive plain-text search. Matches are highlighted, but no lines are removed.
• An invalid Logs regular expression leaves the log text visible.
• Log regular expressions are limited to 200 characters.

Configuration

EDM uses platformdirs to place config.json in the correct user config directory for the operating system. The file is stored in an EDM folder. Typical locations are:

EDM creates this file on first use. On later starts, it keeps valid settings, fills in missing defaults, removes unknown or invalid values, and writes the cleaned configuration back to the file.

edm --no-color disables colors for one run without changing config.json.

Application Logs

EDM writes its own application messages to edm.log beside config.json. This file contains EDM errors and diagnostic messages, not container logs. It rotates at 5 MB and keeps three backup files.

These environment variables can change the logging setup:

EDM_LOG_STDOUT is disabled for 0, false, no, or off. Other values enable it. If EDM cannot create the log file, it prints a warning to the terminal and continues to start.

Development Checks

Run the normal formatting, linting, type, and source-security checks:

make check

Useful individual commands are:

make black
make black-check
make ruff
make ruff-fix
make mypy
make bandit
make test
make integration-test
make smoke-test
make pre-commit
make audit
make security
make package-check

make audit checks installed dependencies for known vulnerabilities. It needs Python 3.10 or newer and network access, so it is not part of make check.

make test prints statement and branch coverage after the unit tests finish. make integration-test starts a temporary Alpine container and checks container listing, logs, environment variables, inspection data, and process information. It requires access to a running local Docker daemon. make smoke-test checks package imports, platform paths, notifier selection, and basic startup on the current operating system.

GitHub Actions runs Black, Ruff, mypy, and Bandit once on Python 3.12. It runs the unit tests on Python 3.9 through 3.14, runs the Docker integration tests on Python 3.12, runs wheel smoke tests on Windows and macOS, and verifies the minimum supported runtime dependency versions on Python 3.9. It also checks dependencies and committed secrets, builds the source distribution and wheel, and installs the wheel on every supported Python version. Dependabot checks Python packages and GitHub Actions each week.

Workflow actions are pinned to full commit SHAs so CI always runs the exact reviewed action code instead of a movable version tag. The comment beside each SHA shows its release version, and Dependabot proposes SHA updates when newer releases are available.

See DEVELOPMENT_GUIDE.md for the code structure, runtime flow, and instructions for extending EDM.

Contributing

Bug reports, feature ideas, and code contributions are welcome. Read CONTRIBUTING.md before opening a pull request.

Please report security problems privately by following SECURITY.md. Do not include sensitive vulnerability details in a public issue.

License

Easy Docker Manager is available under the MIT License.