Getting started
contextzip turns “find the right files, skip node_modules, zip it, find the zip, upload it” into one command. Here's how to go from install to pasted in about a minute.
Watch the walkthrough
Prefer watching? This 72-second video packages a project with cz, pastes it into Claude and writes the reply back with cz apply-zip. Everything below covers the same steps in detail.
Install
Just want one ZIP? Drop a folder on the home page: it runs the same contextzip in your browser, and your files never leave your device. Install it to use it every day, from any project, with the clipboard and apply-zip.
contextzip works on Windows, macOS and Linux. With Python 3.9 or newer, install it with pip, or with pipx or uv to keep it isolated from your projects. Without Python, npm, Homebrew and Scoop install a standalone build of the same tool.
Python 3.9 or newer
You get two commands that do exactly the same thing: contextzip and the shorter cz.
“cz is not recognized” after pip install?
Runpython -m contextzip setup-path and open a new terminal. Why this happens“cz is not recognized”
pip installed contextzip but put the cz command in a folder your terminal doesn't search. It's common with Python from the Microsoft Store or the Python install manager on Windows, and with pip install --user on macOS and Linux. pip even warns about it, in a line that's easy to miss: The scripts cz.exe and contextzip.exe are installed in '…' which is not on PATH.
Python itself always works, so run contextzip through it and let it fix PATH for you:
~/projects/my-app
$ python -m contextzip setup-path
cz is installed in C:\Users\you\AppData\Local\Python\pythoncore-3.13-64\Scripts
That folder isn't on your PATH, so terminals can't find it.
Add it to your user PATH? [Y/n]: y
✓ Added to your user PATH
Open a new terminal, then run cz.
| Installed with | What setup-path does |
|---|---|
| pip on Windows | Adds the folder to your user PATH. No admin rights needed. |
| Microsoft Store Python | Prints a one-line PowerShell command to paste, because the Store sandbox can't change PATH itself. |
| pip on macOS / Linux | Adds one line to your shell's startup file. Use python3 -m contextzip setup-path. |
| pipx / uv | Tells you to run pipx ensurepath or uv tool update-shell. |
Until you open a new terminal, python -m contextzip does everything cz does, for example python -m contextzip apply-zip.
Your first run
From your project root, run it with no flags:
~/projects/my-app
$ contextzip
✓ Detected Next.js + Node.js · high confidence
✓ Scanned 36,220 files & Packed 44 files · 44 included (186 KB), 36,176 excluded, 186 KB → 63 KB, ↓66% smaller
✓ Saved to · .contextzip/output/codebase/codebase.zip · snapshot #1 (k3f9a2)
Full report: .contextzip/output/codebase/codebase.report.txt
✓ Ready to paste
That's real output from running contextzip on this website's own repository: 36,220 files on disk, 44 that actually matter. contextzip detected the stack, left out dependencies, build output, lockfiles, binaries and secrets, and wrote a report next to the ZIP listing exactly what went in and what didn't.
On the very first run in a project, contextzip may offer to open the visual config UI so you can fine-tune what's included. It only asks once, and never in scripts or CI.
Preview before you package
Add--dry-run --verbose to see every included and excluded file without writing anything.Paste it anywhere
When it finishes, the ZIP is on your clipboard as a real file — the same as copying it in your file manager. Click into Claude, ChatGPT, Gemini or any upload box and paste.
| Platform | How the file reaches your clipboard |
|---|---|
| Windows | Set natively (CF_HDROP) and read back to confirm, with PowerShell as a second attempt. |
| macOS | Through Finder, exactly like pressing ⌘C on the file. |
| Linux | A built-in X11 clipboard owner — nothing to install, works under XWayland — or wl-copy / xclip if present. |
If the clipboard can't be used (an SSH session, say), contextzip opens the folder with the ZIP selected and tells you why. Use --no-clipboard to skip this step, or -o path.zip to write the ZIP somewhere specific.
Step-by-step guides for the two most common chats: upload a folder to Claude and upload a codebase to ChatGPT.
Everyday commands
Staying up to date
contextzip update checks PyPI and upgrades in place. It works out whether you installed with pip, pipx or uv and upgrades the same interpreter that's running — never a different pip that happens to be first on your PATH.
~/projects/my-app
$ contextzip update --check
Update available: 0.5.0 → 0.5.1
Run contextzip update to install it.