Sublime Text Docker Integration: Complete Guide

Introduction to Sublime Text Docker Integration

Docker has revolutionized how developers build, ship, and run applications by containerizing environments. Sublime Text, known for its speed and lightweight architecture, is a favorite editor for many developers. Combining these two tools creates a powerful workflow where you can edit code locally in Sublime Text while running, testing, and debugging inside Docker containers. This tutorial walks you through everything you need to know about integrating Docker with Sublime Text, from basic setup to advanced workflows.

What Is Sublime Text Docker Integration?

Sublime Text Docker integration refers to the set of tools, plugins, and workflows that allow you to interact with Docker containers directly from within the Sublime Text editor. Unlike full IDEs such as VS Code or IntelliJ, Sublime Text does not ship with built-in Docker support. Instead, integration is achieved through community plugins, custom build systems, and external tooling that bridges the gap between your editor and the Docker engine.

At its core, the integration enables you to:

• Build and manage Docker images from Sublime Text
• Run containers and view logs inside the editor
• Execute commands inside running containers
• Use Docker as a build system for compiling and running code
• Lint and format code using tools installed in containers

Why Docker Integration Matters

Integrating Docker with your editor solves one of the most persistent problems in software development: the "it works on my machine" dilemma. By running your code inside containers, you ensure consistency across development, staging, and production environments. When this capability is available directly from your editor, you eliminate context switching between terminal windows and your code, dramatically improving productivity.

Here are the key benefits:

• Environment consistency: Your development environment mirrors production exactly.
• Reduced setup time: New team members can start coding with a single docker compose up command.
• Isolated dependencies: No more conflicts between project-specific versions of Node, Python, or other runtimes.
• Seamless workflow: Build, run, and test without leaving Sublime Text.
• Cross-platform compatibility: Develop on macOS, Windows, or Linux with identical container environments.

Prerequisites

Before diving into the integration, ensure you have the following installed and configured:

• Sublime Text 4 (build 4000 or later recommended)
• Package Control for Sublime Text
• Docker Desktop (macOS/Windows) or Docker Engine (Linux)
• Basic familiarity with Docker CLI commands

Verify your Docker installation by running the following command in your terminal:

docker --version
docker compose version

If both commands return version information, you are ready to proceed.

Installing Docker-Related Packages in Sublime Text

Installing Package Control

If you have not already installed Package Control, open the Sublime Text console by pressing Ctrl+` (or Cmd+` on macOS) and paste the installation command from the Package Control website. Restart Sublime Text after installation.

Key Docker Packages

Open the Command Palette with Ctrl+Shift+P (or Cmd+Shift+P on macOS), type "Install Package," and search for the following packages:

• Dockerfile Syntax Highlighting: Provides syntax highlighting for Dockerfiles.
• DockerCompose: Adds syntax support for docker-compose.yml files.
• Terminus: A terminal emulator inside Sublime Text, useful for running Docker commands without leaving the editor.
• SublimeLinter: Works with container-based linters for real-time code analysis.

Setting Up a Docker Build System in Sublime Text

One of the most powerful features of Sublime Text is its build system. You can create custom build systems that run your code inside Docker containers. This means pressing Ctrl+B (or Cmd+B on macOS) can compile and execute your code in a containerized environment.

Creating a Basic Docker Build System

Navigate to Tools > Build System > New Build System and replace the default content with the following configuration. This example runs a Python script inside a Docker container:

{
  "shell_cmd": "docker run --rm -v \"$file_path:/app\" -w /app python:3.12-slim python \"$file_name\"",
  "working_dir": "$file_path",
  "selector": "source.python",
  "file_regex": "^\\s*File \"(...*?)\", line ([0-9]*)"
}

Save the file as DockerPython.sublime-build in the suggested directory. Now, when you open a Python file and press Ctrl+B, Sublime Text will execute the script inside a fresh Python 3.12 container with your current directory mounted at /app.

Creating a Node.js Docker Build System

For JavaScript and Node.js projects, create another build system:

{
  "shell_cmd": "docker run --rm -v \"$file_path:/app\" -w /app node:20-alpine node \"$file_name\"",
  "working_dir": "$file_path",
  "selector": "source.js",
  "file_regex": "^\\s*at (.+?):([0-9]+):([0-9]+)"
}

Save this as DockerNode.sublime-build. This allows you to run any JavaScript file inside a Node 20 container with a single keystroke.

Using Docker Compose in Build Systems

For projects that use docker-compose.yml, you can create a build system that executes commands inside an existing service container:

{
  "shell_cmd": "docker compose exec -T app python \"$file_name\"",
  "working_dir": "$project_path",
  "selector": "source.python"
}

This assumes you have a service named app defined in your docker-compose.yml file and that it is already running. The -T flag disables pseudo-TTY allocation, which is necessary for Sublime Text to capture output correctly.

Running Docker Commands with Terminus

The Terminus package brings a full terminal into Sublime Text, allowing you to run Docker commands without switching applications. After installing Terminus, you can open a terminal tab by selecting Terminus: Open Default Shell in Tab from the Command Palette.

You can also bind a keyboard shortcut to open Terminus. Add the following to your key bindings file (Preferences > Key Bindings):

[
  {
    "keys": ["ctrl+alt+t"],
    "command": "terminus_open",
    "args": {
      "config_name": "Default",
      "cwd": "$file_path"
    }
  }
]

Now, pressing Ctrl+Alt+T opens a terminal in the directory of your current file, ready for Docker commands.

Project Configuration with Docker

Setting Up a .sublime-project File

Sublime Text project files can store custom settings, including Docker-related environment variables and build configurations. Here is an example project file for a Dockerized Python web application:

{
  "folders": [
    {
      "path": ".",
      "folder_exclude_patterns": ["__pycache__", ".venv", "node_modules"],
      "file_exclude_patterns": ["*.pyc", "*.log"]
    }
  ],
  "settings": {
    "tab_size": 4,
    "translate_tabs_to_spaces": true
  },
  "build_systems": [
    {
      "name": "Docker: Run Python",
      "shell_cmd": "docker compose exec -T app python ${file_name}",
      "working_dir": "${project_path}",
      "selector": "source.python"
    },
    {
      "name": "Docker: Run Tests",
      "shell_cmd": "docker compose exec -T app pytest -v",
      "working_dir": "${project_path}",
      "selector": "source.python"
    },
    {
      "name": "Docker: Rebuild and Restart",
      "shell_cmd": "docker compose up -d --build",
      "working_dir": "${project_path}"
    }
  ]
}

With this configuration, you can switch between build systems using Ctrl+Shift+B (or Cmd+Shift+B on macOS) and choose whether to run a single file, execute the test suite, or rebuild the entire stack.

Linting Code Inside Containers

SublimeLinter can use Docker containers as the execution environment for linters. This ensures that your linting tools match the exact versions used in production. To set this up, first install SublimeLinter and the relevant linter plugin (for example, SublimeLinter-pylint for Python).

Configure SublimeLinter to use Docker by adding the following to your Sublime Text user settings (Preferences > Settings):

{
  "sublimelinter": "save-only",
  "sublimelinter_settings": {
    "pylint": {
      "executable": ["docker", "run", "--rm", "-v", "$file_path:/app", "-w", "/app", "my-pylint-image"]
    },
    "eslint": {
      "executable": ["docker", "run", "--rm", "-v", "$file_path:/app", "-w", "/app", "my-eslint-image"]
    }
  }
}

You will need to build custom Docker images that contain your linting tools. Here is an example Dockerfile for a pylint image:

FROM python:3.12-slim
RUN pip install pylint pylint-django
WORKDIR /app
ENTRYPOINT ["pylint"]

Build the image with:

docker build -t my-pylint-image .

Now, every time you save a Python file, SublimeLinter will run pylint inside the container and display inline annotations in your editor.

Formatting Code with Docker-Based Formatters

Code formatters like black (Python) or prettier (JavaScript) can also run inside containers. You can create Sublime Text macros or use the EditorConfig package combined with custom commands. A simpler approach is to create a build system specifically for formatting:

{
  "name": "Docker: Format Python (black)",
  "shell_cmd": "docker run --rm -v \"$file_path:/app\" -w /app my-black-image black \"$file_name\"",
  "working_dir": "$file_path",
  "selector": "source.python"
}

After running this build system, the formatted file will be written back to your local filesystem because the directory is mounted as a volume.

Debugging Inside Docker Containers

Debugging containerized applications from Sublime Text requires a bit more setup. For Python applications, you can use the debugpy library to enable remote debugging. Here is how to set it up.

First, add debugpy to your container's requirements and expose a debug port in your docker-compose.yml:

services:
  app:
    build: .
    ports:
      - "5678:5678"
    volumes:
      - ./:/app
    command: python -m debugpy --listen 0.0.0.0:5678 --wait-for-client app.py

Then, install a Sublime Text debug client plugin such as Debugger from Package Control. Configure it to connect to localhost:5678. When you start the container, it will wait for the debugger to attach before executing your code, allowing you to set breakpoints and inspect variables from within Sublime Text.

Best Practices for Sublime Text Docker Integration

Use Lightweight Base Images

When creating build system containers, always prefer slim or alpine variants. This reduces the time it takes to start a container on every build. For example, python:3.12-slim starts much faster than python:3.12, and node:20-alpine is significantly lighter than node:20.

Cache Volumes for Package Managers

Mounting package manager cache directories as volumes prevents redundant downloads and speeds up container startup. Add cache volume mounts to your build systems:

{
  "shell_cmd": "docker run --rm -v \"$file_path:/app\" -v \"pip_cache:/root/.cache/pip\" -w /app python:3.12-slim python \"$file_name\"",
  "working_dir": "$file_path",
  "selector": "source.python"
}

Use .dockerignore Effectively

Create a .dockerignore file to prevent unnecessary files from being included in your build context. This speeds up builds and reduces image size:

__pycache__/
*.pyc
.venv/
node_modules/
.git/
*.log
.env

Pin Image Versions

Never use latest tags in your build systems or Dockerfiles. Pin specific versions to ensure reproducible builds. For example, use python:3.12.3-slim instead of python:latest.

Leverage Docker Compose for Multi-Service Projects

If your project involves multiple services (for example, a web server, database, and cache), always use Docker Compose. This allows you to start the entire stack with a single command and reference individual services in your Sublime Text build systems.

Keep Build Systems Project-Specific

While global build systems are convenient, project-specific build systems in your .sublime-project file provide better control. They allow you to define exact container images, environment variables, and working directories tailored to each project.

Use Named Volumes for Persistent Data

When working with databases or other stateful services, use named volumes instead of bind mounts to avoid permission issues and improve performance on macOS and Windows:

services:
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: secret

volumes:
  pgdata:

Advanced Workflow: Dev Containers in Sublime Text

While VS Code has native Dev Container support, you can replicate a similar workflow in Sublime Text using a combination of Docker Compose, remote volume mounts, and the Terminus plugin. The idea is to run a container that has all your development tools installed and mount your source code into it.

Here is an example docker-compose.dev.yml for a development container:

services:
  dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - ./:/workspace
      - ~/.gitconfig:/root/.gitconfig:ro
      - ~/.ssh:/root/.ssh:ro
    working_dir: /workspace
    command: sleep infinity
    network_mode: host

Start the container with:

docker compose -f docker-compose.dev.yml up -d

Then, use Terminus to open a shell inside the container:

docker compose -f docker-compose.dev.yml exec dev bash

You can now run all your development commands (testing, linting, building) inside the container while editing files in Sublime Text on your host machine. The changes are instantly reflected in the container because of the volume mount.

Troubleshooting Common Issues

Permission Denied Errors on Mounted Volumes

On Linux, you may encounter permission issues when containers write to mounted volumes. Fix this by ensuring your container user has the same UID as your host user. Add the following to your Dockerfile:

ARG USER_ID=1000
ARG GROUP_ID=1000
RUN groupadd -g ${GROUP_ID} devuser && \
    useradd -u ${USER_ID} -g devuser -m devuser
USER devuser

Build with your actual UID:

docker build --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g) -t my-dev-image .

Slow File Operations on macOS and Windows

Bind mounts can be slow on macOS and Windows due to filesystem translation layers. To mitigate this, use Docker's caching feature or consider using named volumes for directories with high I/O activity. You can also use the :cached flag on macOS:

volumes:
  - ./:/workspace:cached

Build Output Not Showing in Sublime Text

If your Docker build system produces no output, ensure you are using the -T flag with docker compose exec to disable TTY allocation. Also, verify that your shell_cmd uses proper quoting for file paths containing spaces.

Conclusion

Integrating Docker with Sublime Text transforms a lightweight editor into a powerful development environment with all the benefits of containerization. By leveraging custom build systems, the Terminus terminal plugin, SublimeLinter with container-based linters, and Docker Compose for multi-service orchestration, you can build, run, test, and debug your applications entirely within a consistent, reproducible container environment. While Sublime Text may not offer the out-of-the-box Docker integration found in heavier IDEs, its flexibility and extensibility make it more than capable of supporting a robust Docker-based development workflow. By following the best practices outlined in this guide—using lightweight images, pinning versions, caching dependencies, and keeping build systems project-specific—you can create a fast, reliable, and portable development setup that works seamlessly across any platform.