tkopen/pycharm repository overview

⁠PyCharm Community Edition Docker Container

This Docker container provides a quick and easy way to run or try PyCharm Community Edition⁠. It supports both CPU and GPU configurations, with optional integrations for TensorFlow and Jupyter Notebook. The source code for this project is available on the GitLab repository⁠.

This README is designed to be accessible for both junior and expert users. Beginners will find step-by-step instructions with explanations, while experts can skim sections or jump directly to advanced topics. Important Note: Always refer to the official documentation for the most up-to-date instructions. We provide summaries here for convenience, but visit the respective official websites (linked throughout) for complete details and troubleshooting.

⁠Table of Contents

• Base Image Tags⁠
• Optional Features⁠
  • Enabling GPU Support on the Host⁠
• Installing Docker Engine⁠
• Quickly Testing the Images (No Persistence)⁠
• Installing the Docker Compose Plugin⁠
• Using Docker Compose for Persistent Setup⁠
• Tips and Tricks⁠
• Support⁠
• Contributing⁠
• References and Documentation⁠

⁠Base Image Tags

We offer two main image variants:

1. CPU-only: Pre-installed with PyCharm Community Edition. Suitable for general development without GPU acceleration.
2. GPU-accelerated: Includes PyCharm, TensorFlow, and a Jupyter Notebook server. These are based on official TensorFlow images, which require a CPU supporting AVX instructions (most modern CPUs do; check TensorFlow issue #19584⁠ if you encounter problems).

CPU images built after March 2023 are based on Ubuntu 22.04 LTS. CPU images built after July 2025 are based on Ubuntu 24.04 LTS (tags now include the Ubuntu version for clarity). GPU images are based on the official TensorFlow Docker image's base OS, which is Ubuntu 22.04 LTS for TensorFlow 2.19.0.

• CPU tags: :cpu-<ubuntu_version>-<pycharm_version> (e.g., :cpu-24.04-2025.1.3.1). Only PyCharm is pre-installed.
• GPU tags: :gpu-<tensorflow_version>-jupyter-<pycharm_version> (e.g., :gpu-2.19.0-jupyter-2025.1.3.1). Includes PyCharm, TensorFlow, and Jupyter Notebook.
• Latest tags: Use :cpu for the latest CPU image or :gpu for the latest GPU image. Deprecated tags like -devel, -custom-op, and -latest are no longer supported.

All images use Python 3 exclusively (version varies: 3.8 for CPU on Ubuntu 22.04, 3.12 for CPU on Ubuntu 24.04, and 3.11 for GPU based on TensorFlow's official image).

Back to Table of Contents⁠.

⁠Optional Features

• GPU Tags: Based on TensorFlow's official Docker images⁠ and NVIDIA CUDA⁠. Requires NVIDIA Docker⁠ for GPU support. Note: For TensorFlow 1.13+ (including latest tags), ensure your NVIDIA driver supports CUDA 10 or later—check the NVIDIA CUDA compatibility matrix⁠.

  These images include a Jupyter Notebook server and sample TensorFlow tutorials. The container starts Jupyter by default. To persist notebooks, mount a volume to /tf/notebooks (see examples below).

  Alternatively, launch PyCharm on boot and start Jupyter manually from a PyCharm terminal (instructions provided later).

⁠Enabling GPU Support on the Host

To run GPU-accelerated containers, install the NVIDIA Container Toolkit on your host system (e.g., Ubuntu 24.04). This enables Docker to access your NVIDIA GPU.

1. Add the NVIDIA Container Toolkit Repository:

   curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
   curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
     sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
     sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
   

   Copy

2. Update and Install:

   sudo apt-get update
   sudo apt-get install -y nvidia-container-toolkit
   

   Copy

3. Configure Docker:

   sudo nvidia-ctk runtime configure --runtime=docker
   sudo systemctl restart docker
   

   Copy

4. Verify Installation: Run a test container to confirm GPU access:

   docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi
   

   Copy

   This should display your GPU details.

For more details, see the NVIDIA Container Toolkit Installation Guide⁠.

Back to Table of Contents⁠.

⁠Installing Docker Engine

Docker Engine is required to run these containers. Important Note: For the most accurate and current installation steps, visit the official Docker Engine installation guide⁠. The instructions below are for Ubuntu and are summaries—follow the official docs for your OS.

There are two common Docker packages: docker.io (from Ubuntu repositories) and docker-ce (from Docker, Inc.).

⁠docker.io (Ubuntu-Maintained)

• Pros: More stable, but versions may lag.
• Cons: Slower updates for features and security fixes.
• Installation:

  sudo apt-get update
  sudo apt-get install docker.io
  

  Copy

⁠docker-ce (Docker-Maintained, Recommended for Most Users)

• Pros: Latest features, frequent updates.
• Cons: Potentially less tested in Ubuntu-specific environments.
• Installation:

  sudo apt-get update
  sudo apt-get install ca-certificates curl gnupg lsb-release
  curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  sudo apt-get update
  sudo apt-get install docker-ce docker-ce-cli containerd.io
  

  Copy

⁠Post-Installation Steps

After installation:

1. Add your user to the docker group: sudo usermod -aG docker $USER.
2. Log out and log back in (or run newgrp docker) for changes to take effect.
3. Verify: Run id to check group membership, then docker stats to test.

If issues arise, consult the official Docker Engine documentation⁠.

Back to Table of Contents⁠.

⁠Quickly Testing the Images (No Persistence)

These commands run containers temporarily for testing—data is lost on exit. For persistent setups, use Docker Compose (see below).

⁠CPU-Only (Launches PyCharm)

docker run -it --rm \
  -e DISPLAY=unix$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  tkopen/pycharm:cpu pycharm

⁠GPU (Launches PyCharm; Start Jupyter Manually)

docker run -it --rm --gpus all \
  -e DISPLAY=unix$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -p 8888:8888 \
  tkopen/pycharm:gpu pycharm

To start Jupyter from a PyCharm terminal:

jupyter notebook --notebook-dir=/home/coder --ip 0.0.0.0 --no-browser --allow-root

Access at http://localhost:8888⁠ (token shown in terminal).

For persistent notebooks (GPU example):

docker run -it --rm --gpus all \
  -e DISPLAY=unix$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v $HOME/my_notebooks:/tf/notebooks \
  -p 8888:8888 \
  tkopen/pycharm:gpu

⁠Why Persistence Matters

Without volumes, PyCharm settings, code, and data are lost. Key directories to persist:

• /home/coder/.cache
• /home/coder/.java
• /home/coder/.config/JetBrains
• /home/coder/.local/share/JetBrains
• /home/coder/workspace

Use volumes in commands or Docker Compose for persistence.

Back to Table of Contents⁠.

⁠Installing the Docker Compose Plugin

Docker Compose simplifies managing containers, volumes, and networks via a YAML file. Important Note: Visit the official Docker Compose installation guide⁠ for the latest steps.

Installation (Ubuntu):

sudo apt-get update
sudo apt-get install docker-compose-plugin

Verify: docker compose version.

For usage details, see the official Docker Compose documentation⁠.

⁠Using Docker Compose for Persistent Setup

Download docker-compose.yml from the GitLab repository⁠.

Run CPU container:

docker compose -f ~/path/to/docker-compose.yml up pycharm

Run GPU container:

docker compose -f ~/path/to/docker-compose.yml up pycharm-gpu

On first launch, PyCharm prompts to create/open a project. Select "Open" and point to /home/coder/workspace.

Back to Table of Contents⁠.

⁠Tips and Tricks

⁠Error: externally-managed-environment

• Python Virtual Environment for pip Installs (Ubuntu 24.04 and Later): Ubuntu 24.04 enforces PEP 668, marking the system Python (/usr/bin/python3) as "externally managed" to prevent global installs that could conflict with OS packages. This causes errors like error: externally-managed-environment if you run python3 -m pip install <package> without a virtual environment. A venv is pre-created at ~/.local/venv, with its bin added to PATH in ~/.profile. To fix:
  • Run source ~/.profile to update PATH, then python3 -m pip install <package>.
  • Or activate: source ~/.local/venv/bin/activate for direct pip install <package>.
  • Verify with which python3 (should show ~/.local/venv/bin/python3).
  • In PyCharm: Set Terminal > Shell path to /bin/bash -l in Settings.

⁠For Beginners

• Daemon Mode: Run containers in the background with -d: docker compose -f ~/path/to/docker-compose.yml up -d pycharm. Stop with docker compose -f ~/path/to/docker-compose.yml down.
• Docker Hub Login: If you see an "unauthorized" error, run docker login. Sign up for a free account at hub.docker.com⁠.
• X11 Permissions: If PyCharm doesn’t display, run xhost +local:docker to allow Docker to access your display.
• Finding the Jupyter Token: When starting Jupyter, the terminal shows a URL with a token (e.g., http://127.0.0.1:8888/?token=abc123). Copy the token and paste it into your browser to log in.
• Checking Container Status: Use docker ps to see running containers or docker ps -a to see all containers (including stopped ones).

⁠For Advanced Users

• Customizing docker-compose.yml: Edit the YAML file to adjust volumes, ports, or environment variables. For example, change the Jupyter port by modifying ports: ["8888:8888"].
• Resource Limits: Add CPU/memory limits in docker-compose.yml (e.g., deploy: resources: limits: cpus: "2" memory: "4g") to optimize performance.
• GPU Debugging: If GPU acceleration fails, verify CUDA compatibility with nvidia-smi and ensure the NVIDIA Container Toolkit is installed (sudo apt-get install nvidia-container-toolkit).
• Version Pinning: Avoid :cpu or :gpu tags for production to prevent unexpected updates. Use specific tags (e.g., :cpu-24.04-2025.1.3.1).
• Cleaning Up: Remove unused images and volumes with docker system prune or docker volume prune to save disk space.

Back to Table of Contents⁠.

⁠Support

Create an issue on the GitLab project issues page⁠.

Back to Table of Contents⁠.

⁠Contributing

Contributions are welcome to enhance usability across OSes. Submit merge requests via GitLab⁠.

Back to Table of Contents⁠.

⁠References and Documentation

• Official Docker Engine Documentation⁠
• Official Docker Compose Documentation⁠
• Installing Docker Compose on Ubuntu⁠
• Docker Containers on the Desktop⁠

Back to Table of Contents⁠.