---
title: notebookutils: 파일 다루고 다른 Notebook 부르는 도우미
description: Fabric Notebook에 내장된 notebookutils(구 mssparkutils)의 fs, notebook.run/exit, credentials 같은 자주 쓰는 기능을 실무 예제로 소개하고 이름 변경 이력을 짚었어요.
date: 2026-10-03
  tags: [notebookutils, mssparkutils, Notebook, PySpark, Fabric]
cards:
  - /cards/fabric-notebookutils-basics/card-01.png
  - /cards/fabric-notebookutils-basics/card-02.png
  - /cards/fabric-notebookutils-basics/card-03.png
  - /cards/fabric-notebookutils-basics/card-04.png
  - /cards/fabric-notebookutils-basics/card-05.png
  - /cards/fabric-notebookutils-basics/card-06.png
  - /cards/fabric-notebookutils-basics/card-07.png
author: Lissa
source: https://interlinear.work/notes/fabric-notebookutils-basics/
---

> **원문:** [NotebookUtils (former MSSparkUtils) for Fabric](https://learn.microsoft.com/en-us/fabric/data-engineering/notebook-utilities)
> **게시일:** 2025-03-31 · **Microsoft Fabric 설명서**

Fabric Notebook을 열면 별도로 설치하지 않아도 바로 쓸 수 있는 도구 모음이 하나 있어요. 파일을 옮기고, 비밀값을 안전하게 가져오고, 다른 Notebook을 호출하는 것처럼 Spark 코드만으로는 번거로운 일들을 짧은 호출 한 줄로 처리해주는 **notebookutils**예요. PySpark, Scala, SparkR 노트북은 물론 파이프라인에서도 쓸 수 있어요.

## 이름이 왜 두 개예요? mssparkutils와 notebookutils

원래 이 패키지 이름은 **MSSparkUtils**였어요. Fabric이 이 이름을 공식적으로 **NotebookUtils**로 바꿨는데, 기존에 `mssparkutils`로 짜둔 코드가 갑자기 깨지는 일은 없도록 **하위 호환**을 유지하고 있어요. 즉 기존 코드는 그대로 돌아가지만, 새로운 기능과 업데이트는 앞으로 `notebookutils` 네임스페이스에만 들어가고 `mssparkutils`는 언젠가 폐지될 예정이에요. 새로 코드를 짠다면 처음부터 `notebookutils`를 쓰는 게 맞고, `notebookutils`는 **Spark 3.4(런타임 v1.2) 이상**을 전제로 설계됐어요.

## 뭘 할 수 있는지 훑어보기

notebookutils는 기능별로 모듈이 나뉘어 있어요.

| 모듈 | 네임스페이스 | 하는 일 |
| --- | --- | --- |
| 파일 시스템 유틸리티 | `notebookutils.fs` | ADLS Gen2·Blob Storage·Lakehouse 스토리지의 파일·디렉터리 복사, 이동, 읽기, 쓰기, 삭제, 목록 조회 |
| 파일 마운트/언마운트 | `notebookutils.fs` | 원격 스토리지를 Spark 노드에 로컬 마운트 지점처럼 연결 |
| Notebook 실행·오케스트레이션 | `notebookutils.notebook` | 다른 Notebook 실행·체이닝, DAG 기반 병렬 실행, exit 값 처리 |
| Notebook 관리 | `notebookutils.notebook` | Notebook 항목을 코드로 생성·조회·수정·삭제 |
| 자격 증명 유틸리티 | `notebookutils.credentials` | Azure 서비스 액세스 토큰 발급, Key Vault 비밀 조회 |
| Lakehouse 유틸리티 | `notebookutils.lakehouse` | Lakehouse 항목·테이블을 코드로 관리 |

지금 뭐가 있는지 다 기억할 필요는 없고, Notebook 셀에서 직접 물어보면 돼요.

```python
notebookutils.help()          # 전체 모듈 개요
notebookutils.fs.help()       # fs 모듈 상세
notebookutils.notebook.help() # notebook 모듈 상세
```

## fs: 파일 다루기

가장 자주 쓰게 되는 건 역시 `notebookutils.fs`예요. 기본 Lakehouse에 붙어 있는 파일이라면 상대 경로만으로도 접근할 수 있어요.

```python
notebookutils.fs.ls("Files/tmp")  # 기본 Lakehouse의 Files 폴더 아래 목록
notebookutils.fs.mkdirs("Files/new_dir")
```

다른 Lakehouse나 ADLS Gen2, Blob Storage처럼 기본 Lakehouse가 아닌 곳에 접근하려면 `abfss://` 형식의 절대 경로가 필요해요.

```python
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")
```

원격 스토리지를 아예 로컬 경로처럼 마운트해서 표준 파일 입출력 함수로 다루고 싶다면 `notebookutils.fs.mount()`도 있어요. Key Vault에서 액세스 키나 SAS 토큰을 받아와 마운트에 넘기는 식으로 자격 증명을 코드에 직접 하드코딩하지 않고 처리할 수 있어요.

## notebook: 다른 Notebook 부르기, 값 넘기고 받기

`notebookutils.notebook.run()`은 다른 Notebook을 호출하고 그 결과값(exit 값)을 돌려받는 함수예요.

```python
exitVal = notebookutils.notebook.run("Sample1", 90, {"input": 20})
print(exitVal)
```

세 번째 인자는 호출되는 Notebook의 매개변수 셀에 넘길 값이고, 두 번째 인자는 타임아웃(초)이에요. 호출되는 쪽 Notebook은 `notebookutils.notebook.exit()`로 결과를 돌려줘요.

```python
notebookutils.notebook.exit("value string")
```

`exit()`의 동작은 어디서 호출되느냐에 따라 달라요. 대화형으로 직접 실행하면 예외를 던져 뒤 셀을 건너뛰고 세션은 그대로 유지되고, 파이프라인이 이 Notebook을 호출한 경우에는 그 값이 활동의 출력으로 나가면서 파이프라인도 이어서 진행돼요. 여러 Notebook을 한 번에 병렬로 돌리고 싶을 땐 `notebookutils.notebook.runMultiple()`을 쓸 수 있는데, 이건 실행할 Notebook 목록을 DAG(방향성 비순환 그래프) 형태로 정의해서 활동 간 의존 관계와 동시 실행 개수까지 지정할 수 있어요.

## credentials: 비밀값 안전하게 가져오기

Key Vault에 저장해둔 비밀값을 코드에 노출하지 않고 가져오려면 `notebookutils.credentials.getSecret()`을 써요.

```python
accountKey = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
```

이렇게 받아온 값은 셀 출력에도 자동으로 마스킹(비밀 값 수정<sup>1</sup>) 처리되기 때문에, 실수로 화면에 그대로 노출되는 사고를 줄여줘요.

## 정리

notebookutils는 Fabric Notebook에서 파일 조작(`fs`), 다른 Notebook 호출과 값 주고받기(`notebook.run`/`exit`), 안전한 자격 증명 조회(`credentials`)처럼 자주 반복되는 잡일을 표준화해둔 내장 도구예요. 예전 이름인 mssparkutils로 짜둔 코드도 계속 동작하지만, 새 코드라면 처음부터 notebookutils로 시작하는 게 앞으로의 업데이트를 놓치지 않는 길이에요.

---

## 어휘 주석

1. **비밀 값 수정(secret redaction):** Notebook 셀 출력에 Key Vault 비밀 같은 민감한 값이 그대로 찍히지 않도록 자동으로 가려서 보여주는 기능이에요.