ImportError: mysql.connector라는 모듈이 없습니다.

ImportError: No module named mysql.connector 오류는 코드를 실행하는 Python 인터프리터가 mysql.connector 가져오기를 위한 모듈을 찾지 못한다는 뜻입니다. 이 모듈을 제공하는 패키지의 이름은 mysql-connector-python입니다. 일반적인 원인은 패키지가 설치되지 않았거나, 프로그램을 실행하는 인터프리터와 다른 Python 인터프리터용으로 설치된 경우입니다.

ImportError: No module named mysql.connector 오류의 의미

Python은 현재 인터프리터에서 사용할 수 있는 패키지의 모듈을 가져옵니다. 한 환경에 패키지를 설치해도 다른 환경에서 사용할 수 있게 되는 것은 아닙니다. 예를 들어 터미널의 pip는 시스템 Python에 연결되어 있지만, 편집기, 노트북, 예약 작업 또는 가상 환경은 다른 인터프리터를 사용할 수 있습니다.

이 오류는 모듈을 찾지 못했다는 뜻이며, 그 자체로 MySQL 서버에 문제가 있다는 의미는 아닙니다. 먼저 사용하는 인터프리터에 커넥터를 설치한 다음, 같은 인터프리터로 가져오기를 확인하세요. 데이터베이스 연결은 별도의 단계입니다.

사용하는 Python 환경에 mysql-connector-python 설치하기

명령에 지정한 인터프리터로 pip를 실행하려면 Python의 -m pip 형식을 사용하세요. 터미널에서 python -m pip install mysql-connector-python를 실행합니다.

프로그램을 python3으로 시작한다면 python3 -m pip install mysql-connector-python를 사용하세요. Windows에서는 Python 실행기로 인터프리터를 선택할 수 있습니다. 예를 들면 py -m pip install mysql-connector-python와 같습니다. 프로그램을 실행할 때 사용하는 명령으로 바꾸세요. 다른 명령으로 설치하면 패키지가 다른 환경에 설치될 수 있습니다.

프로젝트에서 가상 환경을 사용한다면 설치 전에 가상 환경을 활성화하세요. venv라는 이름의 venv 환경은 macOS 또는 Linux 셸에서 보통 source venv/bin/activate로 활성화합니다. Windows 명령 프롬프트에서는 venv\Scripts\activate.bat, PowerShell에서는 venv\Scripts\Activate.ps1을 사용합니다. 그런 다음 해당 환경의 Python으로 설치 명령을 실행하세요. 활성화하지 않고 환경의 인터프리터를 직접 호출할 수도 있습니다. 예를 들어 macOS 또는 Linux에서는 venv/bin/python -m pip install mysql-connector-python를 사용할 수 있습니다.

설치 확인하기

프로그램에 사용하는 것과 동일한 인터프리터 및 환경에서 다음 예제를 실행하세요.

이 섹션의 코드와 표시되는 레이블 또는 출력은 영어로 유지됩니다.

import mysql.connector

print("mysql.connector import succeeded")

mysql.connector import succeeded

제공된 런타임 결과에 따르면 이 가져오기 확인은 성공했습니다. 상황에 맞게 python, python3, py 또는 프로젝트 인터프리터의 전체 경로로 실행하세요. 성공 메시지는 해당 인터프리터가 mysql.connector를 가져올 수 있다는 뜻입니다. 이 확인은 서버 접근, 자격 증명 또는 네트워크 연결을 검사하지 않습니다. 사용자 환경에서 가져오기에 실패하면 아래의 인터프리터 비교 단계를 진행하세요.

오류가 계속되면 문제 해결하기

설치에 사용한 인터프리터와 오류가 발생한 프로그램을 실행하는 인터프리터를 비교하세요. 각 환경에서 해당 python 명령으로 python -c "import sys; print(sys.executable)"을 실행합니다. 출력되는 실행 파일 경로가 같은 환경을 가리켜야 합니다. 경로가 다르면 프로그램의 인터프리터를 사용해 패키지를 설치하세요. 예를 들어 /path/to/project/venv/bin/python -m pip install mysql-connector-python에서 경로를 프로그램이 보고한 실행 파일 경로로 바꾸면 됩니다.

IDE, 노트북 또는 서비스에서는 설정된 Python 인터프리터나 커널을 확인하세요. 터미널에서 활성화한 환경이 해당 도구의 설정까지 자동으로 바꾸지는 않습니다. 도구에서 사용할 환경을 선택하거나, 도구가 이미 사용하는 인터프리터에 패키지를 설치하세요. 그런 다음 같은 환경에서 가져오기를 다시 확인합니다.

가져오기가 계속 실패하면 설치 명령이 완료되었는지, 예상한 실행 파일을 사용했는지 확인하세요. 해당 실행 파일로 python -m pip show mysql-connector-python를 실행하면 pip가 그 환경에서 패키지를 인식하는지 확인할 수 있습니다. 패키지가 없다면 해당 인터프리터로 다시 설치하세요. pip만 단독으로 실행하면 다른 Python 설치를 가리킬 수 있으므로 이에 의존하지 마세요.

최상위 모듈이 없는 경우와 다른 종속성을 불러오는 중 발생한 오류는 서로 다릅니다. 이 보호된 확인 코드는 예상된 패키지 누락 상황에서 처리되지 않은 트레이스백을 발생시키지 않고 누락된 모듈 이름을 보고합니다. 다른 가져오기 오류도 Python이 별도로 보고하므로 각각 조사해야 합니다.

이 섹션의 코드와 표시되는 레이블 또는 출력은 영어로 유지됩니다.

try:
    import mysql.connector
except ModuleNotFoundError as error:
    print(f"Module not found: {error.name}")
except Exception as error:
    print(f"Import failed: {error}")
else:
    print("mysql.connector import succeeded")

결과는 인터프리터에 설치된 패키지에 따라 달라지므로 고정된 출력은 제시하지 않습니다. 누락된 이름이 mysql 또는 mysql.connector라면 프로그램과 동일한 인터프리터로 mysql-connector-python를 설치하세요. 다른 이름이 보고되면 해당 종속성을 조사하세요. 이를 커넥터 패키지 자체가 없다는 증거로 간주해서는 안 됩니다. 그 밖의 가져오기 오류는 별도로 출력되므로 각각 확인하세요.

가져오기에 성공한 뒤 MySQL에 연결하기

가져오기 확인이 통과하면 mysql.connector.connect(host="<host>", user="<username>", password="<password>", database="<database>")를 호출해 데이터베이스 연결을 시도할 수 있습니다. 자리표시자를 자체 설정의 값으로 바꾸고, 실제 비밀번호를 공유 소스 코드에 넣지 마세요. 이 호출에는 연결 가능한 MySQL 서버와 유효한 연결 정보가 필요하므로 가져오기 확인과는 별개입니다. 가져오기에 성공했다고 해서 서버가 실행 중이거나, 자격 증명이 승인되거나, 네트워크 접근이 허용된다는 뜻은 아닙니다. 이러한 연결 문제는 ImportError 오류와 별도로 진단하세요.