Python | error: externally-managed-environment 에러 해결하기

1. 개요

이번 프로젝트에서 한글 문서와 관련된 항목이 있어 Ubuntu 24.04.2 환경에 설치된 Python으로 pyhwp, pyhwpx를 설치하 아래의 명령어를 실행했다.

$ pip install pyhwp

 

2. 현상

그랬더니 아래와 같은 에러를 만났다.

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    
    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.
    
    See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

 

3. 해결 방법

찾아보니 아래의 명령어를 실행했다. 찾아보지 않았지만, 최근 Debian 계열 리눅스에서는 venv 사용이 강제된 것 같은 느낌이 든다.

$ python3 -m pip config set global.break-system-packages true
Writing to /home/mirinae/.config/pip/pip.conf

 

위 명령어 실행한 이후 PIP로 pyhwp를 설치할 수 있었다.

$ pip install pyhwp
Defaulting to user installation because normal site-packages is not writeable
Collecting pyhwp
  Downloading pyhwp-0.1b15.tar.gz (218 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 218.1/218.1 kB 6.9 MB/s eta 0:00:00
  Preparing metadata (setup.py) ... done
Requirement already satisfied: cryptography in /usr/lib/python3/dist-packages (from pyhwp) (41.0.7)
Collecting lxml (from pyhwp)
  Downloading lxml-6.0.1-cp312-cp312-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl.metadata (3.8 kB)
Requirement already satisfied: olefile>=0.43 in /usr/lib/python3/dist-packages (from pyhwp) (0.46)
Downloading lxml-6.0.1-cp312-cp312-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl (5.3 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 5.3/5.3 MB 7.0 MB/s eta 0:00:00
Building wheels for collected packages: pyhwp
  Building wheel for pyhwp (setup.py) ... done
  Created wheel for pyhwp: filename=pyhwp-0.1b15-py3-none-any.whl size=315458 sha256=f2052d0432c66a599121c96001e43ffc0fd85b020bc18be8cd4cabde080daa3e
  Stored in directory: /home/mirinae/.cache/pip/wheels/8e/13/81/cc88f3dcc6e177769677759fffa4ee79fc8eed460d2a36c0cb
Successfully built pyhwp
Installing collected packages: lxml, pyhwp
  WARNING: The scripts hwp5html, hwp5odt, hwp5proc, hwp5spec, hwp5txt and hwp5view are installed in '/home/mirinae/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.