Lazydocker User Guide

Lazydocker is a terminal user interface (TUI) for managing Docker and Docker Compose. Instead of memorizing docker and docker compose commands and juggling multiple terminal windows, you get a single, mouse-and-keyboard-driven dashboard where every common action — viewing logs, restarting a service, attaching to a container, pruning images, watching live CPU and memory graphs — is one keypress away.

This guide shows you how to install lazydocker, navigate its interface, and perform every task it supports. It is written for developers and operators who already use Docker day-to-day and want a faster way to drive it.

Note

Lazydocker does not create or configure containers, images, or networks from scratch — it manages the Docker objects that already exist on your host. Use it to observe, control, and clean up your running environment. For defining services, you still write Dockerfiles and docker-compose.yml files.

1. Quick Start

Once Docker is running and lazydocker is installed, launch it from any directory:

lazydocker

┌─Project────────┐┌─Logs──Stats──Env──Config──Top───────────────────────┐
│ myproject      ││ web-1  | Listening on :3000                          │
├─Services───────┤│ web-1  | GET / 200 12ms                              │
│ web            ││ db-1   | database system is ready to accept conn...  │
│ db             ││                                                      │
├─Containers─────┤│                                                      │
│ web-1   running││                                                      │
│ db-1    running││                                                      │
├─Images─────────┤│                                                      │
│ node:20        ││                                                      │
├─Volumes────────┤│                                                      │
│ myproject_data ││                                                      │
└────────────────┘└──────────────────────────────────────────────────────┘
 x: menu  ?: keybindings                                    pgup/pgdn: scroll

The left side shows side panels (Project, Services, Containers, Images, Volumes, Networks). The large area on the right is the main panel, which shows details — logs, stats, config, environment — for whatever is selected on the left.

Three things to learn first:

• Move between side panels with the arrow keys, Tab, or the number keys 1–6.
• Move up and down inside a panel with ↑/↓ or k/j.
• Open the menu of available actions at any time by pressing x (or ?). This is the fastest way to discover what you can do without memorizing keybindings.

To quit, press q (or Ctrl+C).

Tip

Press x whenever you are unsure what to do. It opens a context-aware menu listing every keybinding available for the panel you are currently in, with plain-English descriptions.

2. Installation

Lazydocker ships as a single self-contained binary for Linux, macOS, and Windows. Choose the method that matches your platform and package manager.

2.1 Requirements

• Docker ≥ 29.0.0 (Docker Engine API ≥ 1.24)
• Docker Compose ≥ 1.23.2 (optional — only needed for the Services and Project panels)

Important

Lazydocker connects to the Docker daemon, so the daemon must be running and your user must have permission to access the Docker socket. If you can run docker ps from your terminal, lazydocker will work.

2.2 Install methods

Homebrew (macOS / Linux)

The tap is updated more frequently than Homebrew core:

brew install jesseduffield/lazydocker/lazydocker

Or install from Homebrew core:

brew install lazydocker

Scoop (Windows)

scoop install lazydocker

Chocolatey (Windows)

choco install lazydocker

Arch Linux (AUR)

yay -S lazydocker

Go

Requires Go ≥ 1.19:

go install github.com/jesseduffield/lazydocker@latest

Install script (Linux/macOS)

Always review a script before piping it into a shell:

curl https://raw.githubusercontent.com/jesseduffield/lazydocker/master/scripts/install_update_linux.sh | bash

The script installs the binary to $HOME/.local/bin by default. Override the target directory with the DIR environment variable:

curl ...install_update_linux.sh | DIR=/usr/local/bin bash

2.3 Run inside Docker

You can run lazydocker itself as a container by mounting the Docker socket:

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /your/config/path:/.config/jesseduffield/lazydocker \
  lazyteam/lazydocker

Warning

Mounting /var/run/docker.sock into a container grants that container full control of your host's Docker daemon — which is equivalent to root access on the host. Only do this with images you trust.

Note

When lazydocker runs inside a container there is a known limitation: container logs and CPU/memory stats may not display. Run lazydocker directly on the host if you need those.

2.4 Make an alias

If you use lazydocker often, a short alias saves keystrokes:

echo "alias lzd='lazydocker'" >> ~/.zshrc

(Substitute ~/.bashrc or your shell's rc file as appropriate.)

3. Command-Line Options

Lazydocker is primarily a TUI, so it has only a handful of command-line flags. They configure how the session starts; everything else happens inside the interface.

Examples:

# Print the full default config (great for creating your own config.yml)
lazydocker --config

# Launch scoped to specific compose files
lazydocker -f docker-compose.yml -f docker-compose.override.yml

# Launch scoped to a named compose project, even outside its directory
lazydocker -p myproject

# Check your installed version
lazydocker --version

v0.24.2
Date: 2026-04-19T00:00:00Z
BuildSource: binaryRelease
Commit: 7e7aadc
OS: linux
Arch: amd64

Tip

Use lazydocker --config > config.yml as a starting template, then trim it down to only the keys you want to change. See Configuration.

4. The Interface

Lazydocker's screen is divided into side panels (left) and the main panel (right). The side panels are lists of Docker objects; the main panel shows details about whichever item is selected.

4.1 Side panels

Note

The Services and Project panels only appear when lazydocker detects a Compose context — either you launched it from a directory containing a valid docker-compose.yml, or you passed -p. Outside a Compose project, lazydocker shows all containers in a single flat list.

4.2 The main panel and its tabs

When you select an item on the left, the main panel displays information about it across several tabs. Cycle through tabs with ] (next) and [ (previous), or click them with the mouse.

For a container, the tabs are:

For services, images, volumes, and networks, the main panel shows the equivalent details (e.g. image layer history, volume/network config).

4.3 Screen modes (giving panels more room)

Press + to cycle the screen mode forward and _ to cycle it back. The three modes are:

• normal — side panels and main panel share the screen (default).
• half — the focused panel takes up half the screen.
• fullscreen — the focused panel fills the entire screen.

This is handy when you want to read a long log stream or a wide process table without the side panels stealing space.

5. Configuration

Lazydocker works with zero configuration, but nearly every behavior — colors, panel sizes, the exact Docker commands it runs, and your own custom commands — can be customized through a config.yml file.

5.1 Opening your config

The easiest way is from inside lazydocker:

1. Focus the Project panel (press 1).
2. Press o to open the config in your default application, or e to edit it in your $EDITOR/$VISUAL (e.g. vim).

Important

Changes to the config take effect only after you close and re-open lazydocker.

5.2 Config file location

The path depends on your operating system:

Tip

If your config lives at one of the standard paths above, editors with the Red Hat YAML extension get autocompletion and validation automatically. For a non-standard path, add this line to the top of your config:

# yaml-language-server: $schema=https://json.schemastore.org/lazydocker.json

5.3 Common settings

The most useful options live under the gui and logs keys. All keys are optional — set only what you want to change.

gui:
  scrollHeight: 2            # lines scrolled per keypress in the main panel
  language: "auto"           # auto | en | pl | nl | de | tr | fr | es | pt | zh
  border: "rounded"          # rounded | single | double | hidden
  sidePanelWidth: 0.333      # side panels as a fraction of screen width
  showAllContainers: false   # show every container, even those tied to a service
  wrapMainPanel: true        # word-wrap long log lines
  screenMode: "normal"       # normal | half | fullscreen on startup
  containerStatusHealthStyle: "long"   # long | short | icon
  expandFocusedSidePanel: false        # accordion effect for the focused panel
logs:
  timestamps: false
  since: '60m'               # how far back to show logs; '' means all logs
  tail: ''                   # e.g. '200' for the last 200 lines

Tip

If logs appear empty when you first open a container, it is usually because the default logs.since is 60m — only the last hour is shown to keep the machine responsive. Set since: '' to show all logs.

5.4 Theming colors

Set border and selection colors under gui.theme. Each option takes an array of attributes (at most one color plus modifiers like bold):

gui:
  theme:
    activeBorderColor:
      - green
      - bold
    inactiveBorderColor:
      - white
    selectedLineBgColor:
      - blue
    optionsTextColor:
      - blue

Available attributes: default, black, red, green, yellow, blue, magenta, cyan, white, bold, reverse, underline. You may also use a hex color such as "#ff8800".

5.5 Customizing the commands lazydocker runs

Every Docker Compose action lazydocker performs is defined by a command template you can override under commandTemplates. Templates use Go's templating syntax, and {{ .DockerCompose }} expands to your configured compose command. This is how you adapt lazydocker to nonstandard setups (for example, combining multiple compose files globally):

commandTemplates:
  # Point every compose action at multiple files at once
  dockerCompose: docker compose -f docker-compose.yml -f docker-compose.prod.yml
  restartService: '{{ .DockerCompose }} restart {{ .Service.Name }}'
  up: '{{ .DockerCompose }} up -d'
  down: '{{ .DockerCompose }} down'

See the Admin Guide for the complete list of overridable templates.

6. Everyday Tasks

This section is a recipe book. Each task lists the panel you start in and the key you press. Remember: when in doubt, press x to see every available action for the current panel.

6.1 View a container's logs

1. Press 3 to focus the Containers panel.
2. Select a container with ↑/↓.
3. The Logs tab is shown automatically in the main panel. Press ]/[ to switch to other tabs (Stats, Env, Config, Top).
4. To open the full log stream in a dedicated subprocess (no time filter), press m.

6.2 Restart, stop, or pause a container

In the Containers panel, with a container selected:

Note

Stopping and removing are guarded by confirmation prompts. If a container must be stopped before it can be removed, lazydocker offers to force-remove it.

6.3 Manage a Compose service

In the Services panel (2), with a service selected:

6.4 Bring a whole project up or down

From the Services panel:

• U — up the entire project (docker compose up -d).
• D — down the entire project (docker compose down).

6.5 Open a shell in a container

Focus the Containers (or Services) panel, select your target, and press E. Lazydocker suspends itself, drops you into /bin/sh inside the container, and returns to the dashboard when you exit the shell.

6.6 Open a container's web port in your browser

Press w in the Containers or Services panel. Lazydocker opens the container's first published port as an http:// link in your default browser. If the container publishes no ports, nothing happens.

6.7 Watch live CPU and memory graphs

Select a container, then switch to the Stats tab (]). Lazydocker draws ASCII graphs that update once per second. By default it graphs CPU % and Memory %; you can graph nearly any metric — see Customizing stats graphs below.

6.7.1 Customizing stats graphs

Graphs are configured under stats.graphs in your config. statPath points at a field in lazydocker's recorded-stats structure (you can see the full structure as JSON in the Stats tab):

stats:
  graphs:
    - caption: CPU (%)
      statPath: DerivedStats.CPUPercentage
      color: cyan
    - caption: Memory (%)
      statPath: DerivedStats.MemoryPercentage
      color: green

6.8 Filter a list

Press / in any side panel to filter it by a substring. Type your search term; the list narrows as you type. Press Enter to keep the filter and return to the list, or Esc to clear it.

6.9 Show or hide stopped containers

In the Containers panel, press e to toggle whether exited containers are shown.

7. Bulk and Custom Commands

7.1 Bulk commands

Bulk commands act on every item in a panel at once. Press b in any side panel to open the bulk-command menu. For example, the Containers panel's bulk menu lets you stop all containers, remove all containers, or prune containers; the Services panel can up, stop, pull, build, or down the whole project in one step.

7.2 Pruning to reclaim disk space

Pruning removes unused Docker objects. Open the bulk menu (b) in the relevant panel and choose the prune option, or use the options menu (x). You can prune:

• Containers — removes stopped containers.
• Images — removes dangling/unused images.
• Volumes — removes unused volumes.
• Networks — removes unused networks.

Caution

Pruning is irreversible. Removing volumes in particular will delete the data they contain. Lazydocker asks for confirmation, but double-check what you are about to delete.

7.3 Custom commands

Custom commands appear in a menu when you press c in a panel, and let you run your own commands against the selected service or container. Define them under customCommands in your config:

customCommands:
  containers:
    - name: bash
      attach: true
      command: 'docker exec -it {{ .Container.ID }} bash'
      serviceNames: []

Each custom command supports these fields:

Within command you can use these template variables:

• {{ .DockerCompose }} — your configured compose command.
• {{ .Container }} — the selected container (e.g. {{ .Container.ID }}).
• {{ .Service }} — the selected service (e.g. {{ .Service.Name }}).

Tip

Press X (capital) anywhere to run a global custom command that isn't tied to the currently selected item.

7.4 Replacing noisy image-name prefixes

If your images come from a long registry prefix, you can shorten how they display with replacements:

replacements:
  imageNamePrefixes:
    '123456789012.dkr.ecr.us-east-1.amazonaws.com': '<prod>'
    '923456789999.dkr.ecr.us-east-1.amazonaws.com': '<dev>'

8. Keybinding Reference

Lazydocker is fully keyboard-driven (and mouse-aware). The tables below list every binding. The same information is available in-app at any time by pressing x or ?.

8.1 Global (work anywhere)

8.2 Navigation within a panel

8.3 Project panel

8.4 Containers panel

8.5 Services panel

8.6 Images / Volumes / Networks panels

Note

Keybindings are not currently remappable through the config file. The bindings above are fixed.

9. Selecting Text and Using the Mouse

Because lazydocker supports mouse events (clicking panels, scrolling), normal click-and-drag is intercepted by the application.

To select text for copying, hold the Option (macOS) or modifier key your terminal uses for "bypass mouse reporting" while dragging. Alternatively, disable mouse handling entirely:

gui:
  mouseEvents: false

Tip

macOS users with trouble selecting text from logs should also review their terminal emulator's "mouse reporting" setting — iTerm2 and Terminal.app handle the Option-drag bypass differently.

10. Troubleshooting

Each entry below gives the symptom, the cause, and the fix.

Error: client version 1.25 is too old

Cause: An old DOCKER_API_VERSION environment variable is pinning the API version, or your Docker daemon is older than the client expects.

Solution: Lazydocker negotiates the API version with the daemon automatically, so the simplest fix is to unset the override:

unset DOCKER_API_VERSION
lazydocker

Prevention: Avoid setting DOCKER_API_VERSION globally unless a specific tool requires it.

Error: docker-compose: command not found (Project Logs)

Cause: Lazydocker tries docker compose first and falls back to docker-compose; if neither is on your PATH, compose actions fail.

Solution: Install Docker Compose, or point lazydocker at the correct command in your config:

commandTemplates:
  dockerCompose: docker compose

Prevention: Confirm docker compose version runs in your shell before launching lazydocker.

Problem: I can't see my container's logs

Cause: By default lazydocker only shows logs from the last hour (logs.since: '60m') to avoid straining the machine. If your container has been quiet for over an hour, the Logs tab looks empty.

Solution: Show all logs by setting logs.since to an empty string:

logs:
  since: ''

Prevention: Also note that when lazydocker runs inside a Docker container, logs and stats may not display at all — run it on the host instead.

Error: No editor defined in $VISUAL or $EDITOR

Cause: You pressed e to edit the config, but lazydocker can't find an editor. It checks $VISUAL, then $EDITOR, then falls back to vi.

Solution: Set an editor in your shell profile:

export EDITOR=vim

Prevention: Define $EDITOR (or $VISUAL) once in your ~/.bashrc / ~/.zshrc.

Problem: High CPU usage while lazydocker is running

Cause: Continuous log streaming and per-second stats collection have a cost, especially with many containers or very chatty logs.

Solution: Reduce the work lazydocker does: lower the log window (logs.since), set logs.tail to a small number, and turn off gui.wrapMainPanel (wrapping is more CPU-intensive).

logs:
  since: '10m'
  tail: '200'
gui:
  wrapMainPanel: false

Problem: My custom compose project name isn't recognized

Cause: Lazydocker derives the project from the directory or container labels. If your project uses a name: directive or you run lazydocker from outside the project directory, it may not scope correctly.

Solution: Pass the project name explicitly:

lazydocker -p myproject

Error: UI crashes on startup / exec.ExitError exit status 1

Cause: Lazydocker shells out to commands like docker compose config and your editor; a failure in one of those, or a missing terminfo entry (e.g. infocmp not on PATH), can crash startup.

Solution: Run lazydocker --debug and check the log to see which underlying command failed. Ensure docker, docker compose, and infocmp (part of ncurses) are installed and on your PATH.

11. Frequently Asked Questions

Q: How do I edit my config?

Open lazydocker, focus the Project panel (1), and press o to open it (or e to edit it in vim). See Configuration for file locations.

Q: How do I get text to wrap in the main panel?

Set gui.wrapMainPanel: true. Note that wrapping uses more CPU, which is why it is configurable.

Q: How do I select text from the logs?

Because mouse events are captured by lazydocker, hold Option (macOS) while dragging to select text, or disable mouse handling with gui.mouseEvents: false. See Section 9.

Q: Why can't I see logs or stats?

Either the default 1-hour log window is hiding older logs (set logs.since: ''), or you are running lazydocker inside a container, where logs and stats are a known limitation. Run it on the host for full functionality.

Q: Does lazydocker work without Docker Compose?

Yes. Compose is optional. Without it (or outside a compose directory), you still get the Containers, Images, Volumes, and Networks panels; the Services and Project panels simply don't appear.

Q: Can I connect to a remote Docker host?

Yes. Lazydocker honors the standard DOCKER_HOST and DOCKER_CONTEXT environment variables, including ssh:// hosts. Set DOCKER_HOST before launching:

DOCKER_HOST=ssh://user@remote-host lazydocker

Q: How is lazydocker different from Portainer or docui?

Lazydocker is a terminal UI focused on managing existing containers and services. Portainer is browser-based and supports Docker Swarm; docui leans toward creating and configuring containers. They complement each other.

Q: How do I change the display language?

Set gui.language to one of en, pl, nl, de, tr, fr, es, pt, zh, or auto to follow your system locale.

12. Where to Go Next

• For architecture, the complete config reference, deployment patterns (including remote/SSH hosts), and security considerations, see the Admin Guide at Admin Guide.
• The in-app options menu (x) is always the most current reference for what you can do right now.