FTP로 서버에 올린 이미지가 워드프레스 미디어 라이브러리에 안 보이고 나타나지 않는 이유는?

파일 업로드만으로는 워드프레스에 첨부파일 정보가 등록되지 않기 때문이다. 서버에 저장한 이미지를 미디어 라이브러리에서 관리하려면 wp media import 등의 방법으로 별도로 등록해야 한다.

워드프레스에 대량의 이미지 파일들을 한 번에 일괄 등록하는 방법은?

가능하다. wp media import에 여러 파일 경로를 전달하거나 *.webp와 같은 와일드카드를 사용하면 파일들을 일괄 등록할 수 있다. 실행 전에 대상 경로에 등록할 원본 파일만 있는지 확인하는 편이 좋다.

--skip-copy는 어떤 경우에 사용하는가?

로컬 파일을 현재 위치에 그대로 두고 미디어 라이브러리에 등록할 때 사용한다. 이미 업로드 디렉토리에 저장해 둔 이미지를 등록하면서 추가 복사본이 만들어지는 것을 피할 수 있다. 등록 후에도 원본 파일은 해당 경로에 유지해야 한다.

--skip-copy를 사용하면 중복 등록도 방지되는가?

아니다. 이 옵션은 파일 복사를 생략할 뿐이다. 이미 등록한 파일에 같은 명령을 다시 실행하면 첨부파일 정보가 중복 생성될 수 있으므로, 기존 등록 여부를 먼저 확인해야 한다.

워드프레스 멀티사이트 환경에서는 작업 대상 사이트를 어떻게 지정하고 구분하는가?

--path로 워드프레스 설치 경로를 지정하고, --url로 대상 사이트의 주소를 지정한다. 이미지 등록과 메타데이터 수정 명령에 동일한 사이트를 지정하고, 작업 전에 wp option get siteurl로 선택된 사이트를 확인한다.

이미지를 등록하면 작은 크기의 이미지도 자동으로 생성되는가?

기본적으로 워드프레스에 설정된 이미지 크기에 따라 생성된다. 다만 원본 크기와 이미지 생성 설정, 서버의 이미지 처리 기능에 따라 결과가 달라질 수 있다. 파생 이미지가 없다는 이유만으로 등록 실패라고 판단하지 말고 미디어 라이브러리와 명령 실행 결과도 확인해야 한다.

워드프레스에 이미지를 수동으로 업로드할 경우 디렉토리와 파일의 권한은?

디렉토리 755와 파일 644를 사용한다. 다만 소유자와 그룹도 함께 확인해야 한다. 명령 실행 계정은 원본 파일을 읽고 파생 이미지를 저장할 디렉토리에 쓸 수 있어야 하며, 웹 서버도 이미지 경로에 접근하고 파일을 읽을 수 있어야 한다.

이미지 일괄 등록시 이미지마다 다른 제목과 대체 텍스트를 일괄 입력할 수 있는가?

한 번의 등록 명령에서 지정한 제목과 대체 텍스트는 대상 파일에 동일하게 적용된다. 이미지마다 다른 값을 입력하려면 파일별 명령이나 자동화 스크립트를 사용해야 한다. 등록 후에는 첨부파일 ID를 기준으로 각각 수정할 수도 있다.

파일을 등록하면 기존 사이트의 캡션과 설명도 자동으로 이전되는가?

아니다. 파일 등록만으로 기존 사이트의 데이터베이스에 저장된 제목·대체 텍스트·캡션·설명까지 가져오지는 않는다. 기존 값을 유지하려면 해당 정보를 별도로 확보해 등록할 때 전달하거나 등록 후 입력해야 한다.

미디어 라이브러리에 등록하면 게시글 본문에도 자동으로 삽입되는가?

아니다. 미디어 등록과 본문 삽입은 별개의 작업이다. --post_id로 게시글과 첨부 관계를 설정해도 본문에 이미지 태그가 자동으로 추가되지는 않으므로, 편집기나 이미지 삽입 도구로 별도로 배치해야 한다.

워드프레스 이미지 대량 등록: WP-CLI 사용법

작성자 : EQMaker
2026년 10월 13일

안경을 쓴 빅토리아 시대 메이드가 사진이 가득한 양동이를 워드프레스 로고가 그려진 큰 물통에 붓는 모습으로 표현한 WP-CLI 이미지 일괄 등록

FTP로 이미지 파일을 업로드하는 것만으로는 워드프레스 미디어 라이브러리에 등록되지 않는다. WP-CLI의 wp media import를 이용하면 이미지를 한꺼번에 등록할 수 있다. 실제 이미지 45개 이전 사례를 바탕으로 --skip-copy 옵션, 디렉토리와 파일 권한, 작업 대상 사이트 확인, 등록 결과 검증, 제목·대체 텍스트·캡션·설명 입력 방법을 정리한다.

등록할 이미지가 너무 많다.

본 필자가 운영하던 DectENG.com에는 겨우 95개 정도의 게시물만 있었다. 그럼에도 EQMaker.kr로 이전하는 데 3개월 넘는 시간이 걸린 건 모든 게시글을 하나하나 재검토하고 리라이팅했기 때문이었다.

이 과정에서 골치가 아팠던 글 중 하나는 데비안 리눅스 설치 가이드였다. 사실, 글의 분량이 그리 길지는 않은 단일 게시글이었지만 모든 리눅스 설치 단계마다 스크린샷을 첨부한 탓에 하나의 게시글에 무려 45개의 이미지가 붙어 있었다.

다른 게시글들은 기존 게시글에서 이미지를 다운받아 워드프레스의 웹 UI를 통해 미디어 라이브러리에 등록했지만, 45개라는 숫자는 하나씩 하기에는 엄두가 나지 않는 숫자였다. 그렇다고 FTP를 이용해 한 번에 업로드하면 기껏 만들어 놓은 구조화 데이터 출력 모듈에 필요한 첨부파일 메타데이터와 저해상도 이미지가 생성되지 않는다.

수동으로 업로드한 이미지 파일들을 미디어 라이브러리에 등록하면 설정된 크기의 저해상도 이미지도 생성할 수 있고, 미디어 라이브러리에 연동된 사이트의 다른 기능들도 정상적으로 사용할 수 있을 것이다.

그리고 너무나 당연하게도, 이미지 파일을 일괄적으로 등록시키는 방법은 존재한다.

WP-CLI를 이용한 워드프레스 이미지 파일 등록

워드프레스를 관리하는 방법은 관리자 웹페이지에 접속하는 것만 있는 것은 아니다. 워드프레스에는 WP-CLI라는 명령줄 관리 도구가 존재한다.

WP-CLI에서 사용하는 wp 명령은 서버의 명령줄에서 다음과 같은 워드프레스의 기능을 직접 실행할 수 있게 해 준다.

게시글 관리
사용자 관리
플러그인 설치 및 업데이트
데이터베이스 관리
기타 등등

이 가운데 이미지 파일을 미디어 라이브러리에 등록하는 명령이 바로 wp media import 명령 되시겠다.

`wp media import` 명령의 기본 사용법

wp media import 명령의 기본 형식은 다음과 같다.

wp media import <file>... [options]

<file>에는 등록할 파일의 경로와 이름을 지정한다. 와일드카드(*)를 사용해 특정 경로의 여러 파일을 일괄 등록할 수도 있다. 또한 HTTP 또는 HTTPS 주소를 지정해 외부의 이미지 파일을 가져오는 것도 가능하다.

한 가지 기억할 것은, wp media import는 기본적으로 등록 대상 파일을 워드프레스의 업로드 디렉토리에 복사한 다음 복사해 온 파일을 등록한다는 것이다. 본 필자처럼 이미지들을 이미 업로드해 두었다면 같은 이미지의 복사본이 생성된다.

이를 방지하기 위해 사용할 수 있는 옵션이 --skip-copy다. 이 옵션을 추가하면 로컬 파일을 복사하지 않고 현재 경로의 파일을 미디어 라이브러리에 등록한다.

wp media import /path/to/images/*.webp --skip-copy

`wp media import`의 주요 옵션

wp media import는 이미지 파일을 등록하는 것 외에도 제목이나 대체 텍스트 등의 정보를 지정할 수 있는 여러 옵션을 제공한다.

--skip-copy: 로컬 원본 파일을 복사하거나 이동하지 않고 현재 위치에서 등록한다.
--title: 미디어 라이브러리에 표시할 이미지 제목을 지정한다.
--alt: 이미지의 대체 텍스트를 지정한다.
--caption: 이미지의 캡션을 지정한다.
--desc: 이미지의 설명(Description)을 지정한다.
--post_id: 등록한 이미지를 특정 게시글의 첨부파일로 연결한다.
--featured_image: 연결한 게시글의 대표 이미지로 지정한다.
--porcelain: 기본적으로 등록한 파일의 첨부파일 ID만 출력한다.
--path: 작업할 워드프레스 설치 디렉토리를 지정하는 공통 옵션이다.
--url: 멀티사이트 환경에서 작업 대상 사이트의 URL을 지정하는 공통 옵션이다.

참고로 여러 파일을 일괄 등록할 경우 --alt나 --title로 지정한 값은 모든 파일에 동일하게 적용된다. 때문에 이미지마다 서로 다른 메타데이터를 입력하려면 파일별로 명령을 실행하거나 별도의 자동화 스크립트를 만들어야 한다.

대량 이미지 등록 절차

다음은 본 필자가 실제로 데비안 리눅스 설치 게시글에 사용된 45개의 이미지를 워드프레스 미디어 라이브러리에 일괄 등록한 과정이다.

아래에 등장하는 /html/wordpress는 워드프레스가 설치된 디렉토리의 예시 경로다. 실제 작업에서는 자신의 워드프레스 설치 경로와 실행 계정에 맞게 변경해야 한다.

Step 1. 디렉토리 생성과 이미지 업로드

업로드한 파일은 워드프레스 엔진, 즉 웹 서버와 WP-CLI가 접근할 수 있어야 하고, 사용할 디렉토리와 업로드된 파일에는 적절한 권한이 설정되어야 한다. 보통은 아래와 같이 워드프레스의 기본 업로드 경로인 uploads에 업로드하거나 하위 디렉토리를 생성하게 된다.

/html/wordpress/wp-content/uploads/2026/09/debian-install/

이 예제에서는 디렉토리와 파일의 권한을 다음과 같이 설정한다.

디렉토리 권한: 755: 소유자는 읽기, 쓰기, 실행이 가능하며, 그룹과 기타 사용자는 읽기와 디렉토리 접근이 가능하다.
파일 권한: 644: 소유자는 읽기와 쓰기가 가능하며, 그룹과 기타 사용자는 읽기만 가능하다.
소유자 및 그룹: www: 이 예제에서 웹 서버와 WP-CLI 작업에 사용하는 계정과 그룹이다. 실제 작업에서는 서버의 파일 소유권 구성과 PHP 실행 계정에 맞게 지정한다.

WinSCP나 FTP를 이용해 준비해 둔 45개의 WebP 파일을 해당 디렉토리에 업로드하고 디렉토리와 파일의 권한을 변경해 준다.

WinSCP로 Debian 설치 WebP 이미지를 워드프레스 uploads 디렉토리에 일괄 업로드하는 화면 — WinSCP를 이용한 이미지 파일 일괄 업로드

Step 2. 작업 대상 확인과 이미지 파일 개수 확인

SSH나 콘솔을 이용해 워드프레스가 설치된 디렉토리로 이동한다. 일반적으로 wp-config.php가 있는 위치를 기준으로 확인하면 된다.

복수의 사이트를 운영하고 있다면 먼저 작업할 사이트가 올바르게 선택되었는지 확인할 필요가 있다.

eqmaker@wordpress:/html/wordpress$ wp option get siteurl
https://www.eqmaker.kr/media-ops
eqmaker@wordpress:/html/wordpress$

멀티사이트 환경에서는 --url 옵션으로 작업 대상 사이트를 지정한다. 이미지 등록과 메타데이터 수정 명령에도 동일한 대상 사이트를 지정해야 한다.

wp option get siteurl --path=/html/wordpress --url=https://www.eqmaker.kr/media-ops/

사이트 URL이 올바르게 표시되는 것을 확인했다면 등록할 이미지의 개수를 확인한다.

eqmaker@wordpress:/html/wordpress$ find /html/wordpress/wp-content/uploads/2026/09/debian-install/ -maxdepth 1 -type f -name '*.webp' | wc -l
45
eqmaker@wordpress:/html/wordpress$

여기서 find는 지정한 디렉토리에서 파일을 검색하는 명령이고, wc -l은 검색 결과의 줄 수를 계산하는 명령이다.

-maxdepth 1: 지정한 디렉토리의 바로 아래에 존재하는 파일만 검색한다.
-type f: 일반 파일만 검색한다.
-name '*.webp': 확장자가 .webp인 파일만 검색한다.
wc -l: 검색 결과의 줄 수를 세어 파일 개수를 확인한다.

다만 이 명령은 파일의 개수만 확인할 뿐, 파일이 정상적인 이미지인지 또는 워드프레스에 이미 등록되어 있는지는 확인하지 않는다.

Step 3. 이미지 일괄 등록

이미지를 등록할 차례다. 다음 명령으로 서버에 업로드한 45개의 WebP 파일을 워드프레스 미디어 라이브러리에 등록한다.

sudo -u www wp media import /html/wordpress/wp-content/uploads/2026/09/debian-install/*.webp --skip-copy --path=/html/wordpress

여기서 sudo -u www는 www 계정의 권한으로 명령을 실행한다는 의미다.

--skip-copy는 원본 파일을 다시 복사하지 않도록 하는 옵션이며, --path는 작업 대상 워드프레스의 설치 디렉토리를 지정한다. 멀티사이트 환경에서는 작업 대상 사이트의 --url 옵션을 추가한다.

eqmaker@wordpress:/html/wordpress$ sudo -u www wp media import /html/wordpress/wp-content/uploads/2026/09/debian-install/*.webp --skip-copy --path=/html/wordpress
Imported file '/html/wordpress/wp-content/uploads/2026/09/debian-install/01-debian-gnu-linux-13-uefi-installer-menu-install.webp' as attachment ID 884.
Imported file '/html/wordpress/wp-content/uploads/2026/09/debian-install/02-debian-install-select-language-english.webp' as attachment ID 885.
(...중략...)
Imported file '/html/wordpress/wp-content/uploads/2026/09/debian-install/44-debian-grub-boot-menu.webp' as attachment ID 927.
Imported file '/html/wordpress/wp-content/uploads/2026/09/debian-install/debian-website.webp' as attachment ID 928.
Success: Imported 45 of 45 items.
eqmaker@wordpress:/html/wordpress$

총 45개의 이미지가 모두 정상적으로 등록되었다. 첨부파일 ID는 워드프레스가 미디어 파일에 부여하는 고유한 번호로, 이후 메타데이터 수정이나 이미지 연결 등의 작업에 사용할 수 있다.

Step 4. 이미지 등록 결과 확인

워드프레스는 기본적으로 이미지를 미디어 라이브러리에 등록할 때 원본 이미지를 분석하고, 설정된 크기에 따라 썸네일이나 본문 표시용 이미지를 추가로 생성한다. 정상적으로 등록이 완료되었다면 해당 이미지 파일 디렉토리에 작은 크기의 이미지 파일이 생성된 것을 확인할 수 있다. 다만 원본 이미지의 크기나 이미지 생성 설정에 따라 일부 크기의 파일은 생성되지 않을 수 있다.

워드프레스 미디어 등록 후 원본 WebP와 여러 크기의 서브사이즈 이미지가 생성된 디렉토리 — 미디어 등록 후 자동으로 생성된 여러 크기의 서브사이즈 이미지

작은 이미지가 생성되지 않았다면 이미지 크기 설정과 원본 크기를 먼저 확인한다. 생성 대상인데도 파일이 없다면 디렉토리 쓰기 권한과 서버의 이미지 처리 기능, 명령 실행 중 출력된 경고나 오류를 확인해야 한다.

다음으로 워드프레스 관리자 페이지의 미디어 → 라이브러리에 접속해 조금 전 등록한 이미지들이 표시되는지 확인한다. 파생 이미지 생성 여부와 미디어 라이브러리 등록 여부는 각각 확인하는 편이 좋다.

대량 등록한 Debian 설치 이미지가 워드프레스 미디어 라이브러리에 표시된 화면 — WP-CLI로 일괄 등록한 이미지가 워드프레스 미디어 라이브러리에 표시된 모습

웹 UI를 통해 등록한 이미지와 동일하게 이미지를 선택하고 제목, 대체 텍스트, 캡션, 설명 등을 편집할 수도 있다.

추가. 이미지 메타데이터 입력

필요하다면 WP-CLI의 wp post update 명령을 이용해 미디어 파일의 제목, 캡션, 설명 등을 수정할 수 있다.

본 필자는 기존 DectENG의 파일을 이전하면서 이미지와 메타데이터를 모두 직접 확인하고 수정해야 했기 때문에 메타데이터를 웹 UI에서 직접 입력해 주었다. 하지만 기존의 메타데이터 값을 그대로 입력하고자 한다면 아래의 명령을 사용할 수도 있다.

예를 들어 첨부파일 ID가 884번인 이미지의 메타데이터를 수정하려면 다음과 같이 입력할 수 있다.

wp post update 884 \
  --post_title='이미지 제목' \
  --post_excerpt='이미지 캡션' \
  --post_content='이미지 설명' \
  --path=/html/wordpress

여기서 post_title은 이미지 제목, post_excerpt는 캡션, post_content는 설명을 의미한다. 이미지의 작성자를 변경하려면 --post_author 옵션에 워드프레스 사용자 ID를 지정할 수도 있다.

이미지의 대체 텍스트는 별도의 메타데이터로 저장되기 때문에 아래와 같이 wp post meta update 명령을 사용해야 한다.

wp post meta update 884 _wp_attachment_image_alt '이미지 대체 텍스트' --path=/html/wordpress

멀티사이트 환경에서는 메타데이터 수정 명령에도 작업 대상 사이트의 --url 옵션을 추가한다.

마무리

워드프레스는 등록된 멀티미디어 파일에 대한 메타데이터뿐 아니라 여러 부가적인 기능도 제공해 준다. 이러한 미디어 관리 기능을 활용하려면 해당 파일이 워드프레스의 미디어 라이브러리에 등록되어 있어야 한다.

때문에 FTP 등을 이용해 콘텐츠를 이전하거나 대량의 이미지 등록이 필요한 경우, WP-CLI를 이용하면 작업에 필요한 시간을 대폭 줄일 수 있다.

물론, 가장 좋은 것은 이전할 일 없이 애초에 첫 단추를 잘 끼우고 체계를 세워 잘 유지하는 것이긴 하다… ㅜㅜ

FAQ

FTP로 서버에 올린 이미지가 워드프레스 미디어 라이브러리에 안 보이고 나타나지 않는 이유는?: 파일 업로드만으로는 워드프레스에 첨부파일 정보가 등록되지 않기 때문이다. 서버에 저장한 이미지를 미디어 라이브러리에서 관리하려면 wp media import 등의 방법으로 별도로 등록해야 한다.
워드프레스에 대량의 이미지 파일들을 한 번에 일괄 등록하는 방법은?: 가능하다. wp media import에 여러 파일 경로를 전달하거나 *.webp와 같은 와일드카드를 사용하면 파일들을 일괄 등록할 수 있다. 실행 전에 대상 경로에 등록할 원본 파일만 있는지 확인하는 편이 좋다.
--skip-copy는 어떤 경우에 사용하는가?: 로컬 파일을 현재 위치에 그대로 두고 미디어 라이브러리에 등록할 때 사용한다. 이미 업로드 디렉토리에 저장해 둔 이미지를 등록하면서 추가 복사본이 만들어지는 것을 피할 수 있다. 등록 후에도 원본 파일은 해당 경로에 유지해야 한다.
--skip-copy를 사용하면 중복 등록도 방지되는가?: 아니다. 이 옵션은 파일 복사를 생략할 뿐이다. 이미 등록한 파일에 같은 명령을 다시 실행하면 첨부파일 정보가 중복 생성될 수 있으므로, 기존 등록 여부를 먼저 확인해야 한다.
워드프레스 멀티사이트 환경에서는 작업 대상 사이트를 어떻게 지정하고 구분하는가?: --path로 워드프레스 설치 경로를 지정하고, --url로 대상 사이트의 주소를 지정한다. 이미지 등록과 메타데이터 수정 명령에 동일한 사이트를 지정하고, 작업 전에 wp option get siteurl로 선택된 사이트를 확인한다.
이미지를 등록하면 작은 크기의 이미지도 자동으로 생성되는가?: 기본적으로 워드프레스에 설정된 이미지 크기에 따라 생성된다. 다만 원본 크기와 이미지 생성 설정, 서버의 이미지 처리 기능에 따라 결과가 달라질 수 있다. 파생 이미지가 없다는 이유만으로 등록 실패라고 판단하지 말고 미디어 라이브러리와 명령 실행 결과도 확인해야 한다.
워드프레스에 이미지를 수동으로 업로드할 경우 디렉토리와 파일의 권한은?: 디렉토리 755와 파일 644를 사용한다. 다만 소유자와 그룹도 함께 확인해야 한다. 명령 실행 계정은 원본 파일을 읽고 파생 이미지를 저장할 디렉토리에 쓸 수 있어야 하며, 웹 서버도 이미지 경로에 접근하고 파일을 읽을 수 있어야 한다.
이미지 일괄 등록시 이미지마다 다른 제목과 대체 텍스트를 일괄 입력할 수 있는가?: 한 번의 등록 명령에서 지정한 제목과 대체 텍스트는 대상 파일에 동일하게 적용된다. 이미지마다 다른 값을 입력하려면 파일별 명령이나 자동화 스크립트를 사용해야 한다. 등록 후에는 첨부파일 ID를 기준으로 각각 수정할 수도 있다.
파일을 등록하면 기존 사이트의 캡션과 설명도 자동으로 이전되는가?: 아니다. 파일 등록만으로 기존 사이트의 데이터베이스에 저장된 제목·대체 텍스트·캡션·설명까지 가져오지는 않는다. 기존 값을 유지하려면 해당 정보를 별도로 확보해 등록할 때 전달하거나 등록 후 입력해야 한다.
미디어 라이브러리에 등록하면 게시글 본문에도 자동으로 삽입되는가?: 아니다. 미디어 등록과 본문 삽입은 별개의 작업이다. --post_id로 게시글과 첨부 관계를 설정해도 본문에 이미지 태그가 자동으로 추가되지는 않으므로, 편집기나 이미지 삽입 도구로 별도로 배치해야 한다.