【初心者向け】npmとnpxの違いとは?Windowsでnpxを使う方法と動かないときの対処も解説 | Recurrent Hub
【初心者向け】npmとnpxの違いとは?Windowsでnpxを使う方法と動かないときの対処も解説 パッケージ管理のnpm、コマンド実行のnpx。それぞれの役割を正しく理解し、自作ツール開発の第一歩を踏み出そう。 Node.jsを触っていると必ず出会うnpmとnpx。
「npm installはよく使うけど、npxって何が違うの?」
「なんとなく使っているけど、実はよく分かっていない…」
「自分で作ったツールをコマンドみたいに使ってみたいけど、npmに公開するのはハードルが高い…」
そんな風に感じていませんか?
npmとnpxは、セットで理解することでNode.jsのエコシステムを最大限に活用できる、非常に強力なツールです。そして何より、 ことを知れば、開発の幅はぐっと広がります。
必ずしもnpmにパッケージを公開しなくても、ローカル環境で自作のツールを開発し、手軽に利用できる
この記事では、npmとnpxの明確な違いから、実際に簡単なパッケージやCLIツールを自作し、ローカルで利用する手順まで、より実践的なコードを交えてステップバイステップで解説します。
Windowsユーザー向けの注意点 も併せて紹介するので、OSを問わず安心して学べます。
この記事で得られること/できるようになること
npmとnpxの役割の違いが明確に理解できる
Windowsでnpxを使う方法と、PowerShellで動かないときの対処がわかる
実用的なnpmパッケージを自作し、ローカルの別プロジェクトから利用できるようになる
コマンドライン引数を扱えるCLIツールを自作し、ローカルで実行できるようになる
npm linkを使った効率的なローカル開発のテクニックが身につく
Windows・macOS・Linuxの違いを理解した上で、自作パッケージを使いこなせる
npmとは?パッケージの「管理人」 👨💼 npm (Node Package Manager) は、その名の通りNode.jsのパッケージを管理する ためのツールです。
依存関係の管理 : プロジェクトで利用するライブラリ(パッケージ)をpackage.jsonファイルで管理します。npm installコマンドで必要なパッケージを一括でインストールできます。
ライブラリの導入 : npm install <パッケージ名>で、世界中の開発者が公開している便利なパッケージを簡単に自分のプロジェクトに追加できます。
スクリプトの実行 : package.jsonのscriptsに登録したコマンドをnpm run <スクリプト名>で実行できます。(例: npm run start, npm run build)
npmは、プロジェクトに必要な道具(パッケージ)を揃えたり、管理したり、決まった手順(スクリプト)を実行したりする、縁の下の力持ち、いわば「管理人 」のような存在です。
npxとは?パッケージを「実行する」便利屋さん 🏃♂️ 一方、npx (Node Package Executer) は、npm 5.2から同梱されるようになった、パッケージを実行する ためのツールです。
npxの最大のメリットは、パッケージをローカルにインストールすることなく、一度きりで実行できる 点にあります。
# create-react-appを一度きり実行してプロジェクトを作成
npx create-react-app my-app
npxの動作原理 : npxはコマンドを実行する際、まずローカルのnode_modules/.binやシステムグローバルにコマンドが存在するか探します。見つからない場合、npmレジストリからパッケージを一時的にダウンロード し、実行可能な領域(キャッシュ)に配置して実行します。実行が終わると、そのパッケージは自動的にクリーンアップ されるため、システムを汚すことがありません。
npxは、必要なときにサッと現れてコマンドを実行してくれる、いわば「便利な実行屋さん 」です。たまにしか使わないコマンドや、お試して使ってみたいパッケージを実行するのに非常に役立ちます。
一目でわかる!npmとnpxの違い 比較表 項目 npm npx 主な役割 パッケージ管理 (インストール、更新など) パッケージ実行 公開必要? 必須ではない (ローカルでも可) 必須ではない (ローカルでも可) 主な利用場面 ・プロジェクトの依存関係管理 ・ライブラリの導入 ・CLIツールの実行 ・パッケージのお試し利用 コマンド例 npm install eslintnpx eslint .
Windowsでnpxを使う方法 Windowsでも、Node.jsをインストールすればnpxは一緒に入ります。Node.jsのフォルダ(例:C:\Program Files\nodejs)には、npx・npx.cmd・npx.ps1の3つのファイルが置かれます。コマンドプロンプトでもPowerShellでも、npx パッケージ名で実行できます。
PowerShellで「スクリプトの実行が無効」と出て動かないとき PowerShellでnpxを実行すると、次のエラーで止まることがあります(PowerShellの実行ポリシーをRestrictedにして再現したもの)。
npx : File C:\Program Files\nodejs\npx.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
日本語表示の環境では、同じ内容(スクリプトの実行が無効になっているためnpx.ps1を読み込めない)が日本語で表示されます。
原因は、PowerShellがnpxをnpx.ps1(PowerShellのスクリプト)として実行しようとし、実行ポリシーでスクリプトの実行が禁止されているためです。Get-Command npx -Allで確かめると、npx.ps1が先に見つかっていることがわかります。
npx.cmdと書いて実行する (設定を変えずにすぐ使える)
npx . cmd -- version
実行ポリシーがRestrictedのままでも、この形なら動くことを確かめました。
コマンドプロンプト(cmd.exe)で実行する :コマンドプロンプトはnpx.cmdを使うので、実行ポリシーの影響を受けません。
自分のユーザーだけ実行ポリシーをRemoteSignedにする
Get-ExecutionPolicy - List
Set-ExecutionPolicy - Scope CurrentUser RemoteSigned
RemoteSignedは、ローカルで作ったスクリプトは実行でき、インターネットから入手したものとしてマークされた署名のないスクリプトは原則として止める設定です。変更したら、Get-ExecutionPolicyで実際に効いているポリシーを確かめます。グループポリシー(会社のPCの管理設定など)が決めている場合は、自分では変更できず、そちらが優先されます。PCのセキュリティ設定を変える操作なので、会社のPCでは管理者のルールに従ってください。詳しくはMicrosoftのabout_Execution_Policies を参照してください。
実践編①:実用的なnpmパッケージを作ってローカルで使ってみよう 他のプロジェクトからrequireやimportで呼び出して使える、基本的なnpmパッケージの作り方を学びます。
ステップ1: パッケージの作成 作業用のディレクトリを作成し、その中でnpm initを実行します。今回はスコープ付きパッケージとして作成します。これにより、他のユーザーが公開しているパッケージ名との重複を避けることができます。
# ディレクトリを作成して移動
mkdir my-npm-package
cd my-npm-package
# スコープ付きでpackage.jsonを生成 (@your-usernameはご自身のnpmユーザ名に)
npm init --scope=@your-username -y
次に、パッケージの本体となるindex.jsファイルを作成します。単一の関数だけでなく、複数の機能を提供できるよう、オブジェクトをエクスポートするのが一般的です。
// 複数の関数や値をエクスポートする
module.exports = {
sayHello: (name = 'world') => {
console.log(`Hello, ${name} from my awesome npm package!`);
},
version: '1.0.0'
};
ステップ2: ローカルで利用する (npm link) 作成したパッケージを、公開せずに 別のプロジェクトから利用してみましょう。
パッケージをリンク可能にする
my-npm-packageディレクトリで以下のコマンドを実行し、PC内にこのパッケージへの「リンク」を作成します。
Bash
# my-npm-package ディレクトリで実行
npm link
利用側プロジェクトでリンクする
次に、このパッケージを利用したい別のプロジェクト(例: my-app)で、先ほど作成したパッケージ(@your-username/my-npm-package)をリンクします。
Bash
# my-app ディレクトリを作成して移動
mkdir ../my-app && cd ../my-app
npm init -y
# パッケージ名を指定してリンク
npm link @your-username/my-npm-package
動作確認
my-appディレクトリにapp.jsを作成して、パッケージを呼び出してみましょう。
app.js
JavaScript
// パッケージを読み込む
const myPackage = require('@your-username/my-npm-package');
// 実行!
myPackage.sayHello('Developer');
console.log('Package version:', myPackage.version);
実行すると、無事にメッセージとバージョンが表示されるはずです。
Bash
node app.js
#=> Hello, Developer from my awesome npm package!
#=> Package version: 1.0.0
このようにnpm linkを使えば、パッケージをnpmに公開する前に、ローカルで徹底的にテスト・開発を進めることができます。
(任意) ステップ3: npmに公開する # npmにログイン (初回のみ)
npm login
# パッケージを公開 (スコープ付きパッケージは--access publicが必要)
npm publish --access public
※注意: package.jsonのnameは世界中でユニーク(一意)である必要がありますが、スコープ付きにすることでその心配がほぼなくなります。
実践編②:引数が使えるnpxツールを作ってみよう 次に、npx my-cli-tool <引数>のように、引数を渡して動的に動作を変えられるCLIツールを作成します。
ステップ1: CLIツールの作成 作業用ディレクトリ(例: hello-cli)を作成し、npm initを実行します。
binフィールドに加え、authorやlicenseなど、公開を視野に入れた情報を記載します。
{
"name": "@your-username/hello-cli",
"version": "1.0.0",
"description": "A simple CLI tool example that greets the user.",
"main": "index.js",
"bin": {
"hello-cli": "./index.js"
},
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": ["cli", "example", "hello-world"],
"author": "Your Name <your.email@example.com>",
"license": "MIT"
}
次に、実行ファイル本体のindex.jsを作成します。
一行目の#!/usr/bin/env nodeは、このファイルがNode.jsで実行されるスクリプトであることを示す シバン (Shebang) です。
process.argvを使ってコマンドライン引数を取得し、処理を分岐させます。
#!/usr/bin/env node
// process.argvには実行パスやファイルパスが含まれるため、3番目以降が引数になる
const args = process.argv.slice(2);
if (args.length === 0) {
console.log("Hello! This is my first CLI tool! Try passing your name as an argument.");
} else {
// 最初の引数を名前として挨拶する
console.log(`Hello, ${args[0]}! Welcome to my first CLI tool!`);
}
ステップ2: ローカルで実行する これもnpm linkを使えば、公開せずにローカルでテストできます。
コマンドをリンクする
hello-cliディレクトリでnpm linkを実行します。
Bash
# hello-cli ディレクトリで実行
npm link
実行してみる
ターミナルで、設定したコマンド名(hello-cli)を引数あり・なしで実行してみましょう。
Bash
# 引数なし
hello-cli
#=> Hello! This is my first CLI tool! Try passing your name as an argument.
# 引数あり
hello-cli Gemini
#=> Hello, Gemini! Welcome to my first CLI tool!
見事、引数によって動作が変わる自作コマンドが実行できました!
応用と注意点
💡 npm versionでスマートにバージョン管理 パッケージを更新したら、バージョン番号を更新するのが作法です。npm versionコマンドを使えば、package.jsonのバージョンを更新し、Gitのタグ付けまで自動で行えます。
# バージョンを0.0.1上げる (例: 1.0.0 -> 1.0.1)
npm version patch
# バージョンを0.1.0上げる (例: 1.0.1 -> 1.1.0)
npm version minor
# バージョンを1.0.0上げる (例: 1.1.0 -> 2.0.0)
npm version major
🔧 トラブルシューティングとTips
(Unix系OS)実行できない?実行権限を確認しよう
npm linkでコマンドが実行できない場合、スクリプトファイルに実行権限がない可能性があります。以下のコマンドで権限を付与してください。
chmod +x index.js
お片付けも忘れずに!npm unlink
ローカルでの開発が終わったら、作成したリンクを解除してクリーンな状態に戻しましょう。
Bash
# 利用側プロジェクトで実行
npm unlink @your-username/package-name
# パッケージのディレクトリで実行(グローバルリンクを削除)
npm unlink
公開する前に:セキュリティに関する注意点
パッケージを公開する際は、タイポスクワッティング(有名パッケージに似た名前で悪意あるコードを公開する攻撃)を避けるため、パッケージ名は慎重に選びましょう。スコープ付きパッケージはこれを防ぐ有効な手段です。
💻 Windowsユーザー向け補足 npmやnpxの基本動作はWindowsでもmacOS/Linuxと同じ ですが、いくつか注意点があります。
1. シバン行(#!/usr/bin/env node)
💡 シバン行ってなに?
プログラムの一番上に書く「このファイルはどのアプリで動かすのか」を伝える合図のことです。
Node.js の場合はこう書きます:
#!/usr/bin/env node
これがあると、ターミナルで
./index.js
のようにファイル名だけで実行できるようになります。
(「このファイルはNode.jsで動かしてね」と最初に宣言してあるイメージです)
macOS/Linux → この合図がそのまま有効
Windows → 直接は使われませんが、npm linkをすると裏で自動的に .cmd ファイルが作られるので、気にせずそのまま使えます
2. 実行権限(chmod)
3. パス区切り
4. npxのキャッシュ場所 キャッシュの場所は設定で変えられます。npm config get cacheで表示されるフォルダの中にある_npxが、npxのキャッシュです。古い版が使われているようなら、npx パッケージ名@latestのように版を指定して実行します。
リンクとセキュリティの注意
まとめ
npm は、パッケージをインストール・管理する「管理人」
npx は、パッケージを気軽に一時実行する「便利屋さん」
npm link を使えば、npmに公開しなくてもローカルで開発・利用できる
WindowsでもmacOS/Linuxとほぼ同じ手順 で動作(権限設定だけ不要)
PowerShellでnpxが「スクリプトの実行が無効」で止まったら、npx.cmdで実行するか、実行ポリシーを見直す
自作のCLIツールは、日々の定型作業を自動化し、開発効率を大きく高めます。ぜひこの記事を参考に、あなた専用の「便利屋さん」ツール 作りに挑戦してみてください。