{"id":4594,"library":"jupyter-packaging","title":"Jupyter Packaging Utilities","description":"Jupyter Packaging provides utility functions and `setuptools` build command classes to simplify the packaging of Jupyter applications and extensions, particularly those with front-end (JavaScript/TypeScript) assets. It helps integrate pre-build steps into the Python packaging process. The current version is 0.12.3, and it typically sees releases for bug fixes, maintenance, and enhancements related to packaging standards and dependencies.","status":"active","version":"0.12.3","language":"python","source_language":"en","source_url":"https://github.com/jupyter/jupyter-packaging/","tags":["jupyter","packaging","setuptools","build","frontend","extension"],"install":[{"cmd":"pip install jupyter-packaging","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core build dependency for integrating with Python packaging.","package":"setuptools","optional":false},{"reason":"Required for building front-end (JavaScript/TypeScript) assets for Jupyter extensions.","package":"Node.js/npm/yarn","optional":true}],"imports":[{"note":"Used to wrap setuptools commands like 'install' or 'develop' with pre- and post-build steps.","symbol":"wrap_installers","correct":"from jupyter_packaging import wrap_installers"},{"note":"A utility builder class for executing Node.js package manager commands (npm or yarn) as part of the build process.","symbol":"npm_builder","correct":"from jupyter_packaging import npm_builder"},{"note":"As of `setuptools` v61.0.0, `bdist_wheel` moved from the `wheel` package into `setuptools` itself. `jupyter-packaging` v0.12.0 updated its internal import path to reflect this, but older versions of `jupyter-packaging` might break if used with newer `setuptools` versions.","wrong":"from wheel.bdist_wheel import bdist_wheel","symbol":"bdist_wheel","correct":"from setuptools.command.bdist_wheel import bdist_wheel"}],"quickstart":{"code":"from setuptools import setup\ntry:\n    from jupyter_packaging import wrap_installers, npm_builder\n    \n    # Define the builder for npm commands\n    # Assumes a package.json in the root that defines 'build' and 'build:dev' scripts\n    builder = npm_builder(build_cmd='build', develop_cmd='build:dev')\n    \n    # Wrap the 'install' and 'develop' commands with the npm builder\n    cmdclass = wrap_installers(pre_develop=builder, pre_dist=builder)\nexcept ImportError:\n    # Fallback for when jupyter_packaging is not available (e.g., during sdist build)\n    cmdclass = {}\n\nsetup(\n    name='my_jupyter_extension',\n    version='0.1.0',\n    cmdclass=cmdclass,\n    # Other setup arguments like packages, include_package_data, etc.\n    packages=['my_jupyter_extension'],\n    include_package_data=True,\n    # Make sure to include MANIFEST.in for data files not in Python packages\n    # (e.g., JS/CSS assets, Jupyter config files)\n)","lang":"python","description":"This quickstart demonstrates how to integrate `jupyter-packaging` into a `setup.py` file to handle front-end build steps for a Jupyter extension. It uses `npm_builder` to define pre-build commands for both development (`develop`) and distribution (`dist`) modes, ensuring that JavaScript/TypeScript assets are compiled before the Python package is installed or built. The `try/except ImportError` block allows the `setup.py` to be run even if `jupyter-packaging` is not installed, which can be useful during initial `sdist` creation or local testing."},"warnings":[{"fix":"Upgrade `jupyter-packaging` to version 0.12.0 or later. Ensure your `setup.py` or `pyproject.toml` specifies a compatible `jupyter-packaging` version.","message":"When upgrading `setuptools` to version 61.0.0 or higher, projects using `jupyter-packaging` versions prior to 0.12.0 may encounter `ImportError` due to a change in the internal import path for `bdist_wheel`.","severity":"breaking","affected_versions":"<0.12.0"},{"fix":"Ensure your project targets Python 3.7 or newer. Upgrade your Python environment if necessary.","message":"Support for Python 3.6 was dropped with the release of `jupyter-packaging` 0.11.0.","severity":"deprecated","affected_versions":"<0.11.0"},{"fix":"Install Node.js (which includes npm) and optionally yarn in your build environment. Verify their availability by running `node -v` and `npm -v` (or `yarn -v`).","message":"Building Jupyter extensions with front-end assets typically requires Node.js and a package manager (npm or yarn) to be installed and available in the system's PATH, as `jupyter-packaging` will execute these tools.","severity":"gotcha","affected_versions":"All"},{"fix":"Configure `jupyter-packaging` as a build requirement in your `pyproject.toml` (e.g., `requires = [\"jupyter_packaging>=0.10,<2\"]`) or ensure it's only installed in build environments.","message":"`jupyter-packaging` is primarily intended as a *build-time* dependency, not a *runtime* dependency. It should be listed in `build-system.requires` in `pyproject.toml` rather than `install_requires` in `setup.py` or `dependencies` in `pyproject.toml` for most projects.","severity":"gotcha","affected_versions":"All"},{"fix":"Instead of `python setup.py sdist` or `python setup.py bdist_wheel`, use `pip install build` followed by `python -m build .`.","message":"`jupyter-packaging` does not support the deprecated `python setup.py bdist_wheel` or `python setup.py sdist` commands directly. The recommended approach for building distributions is to use the `build` package.","severity":"gotcha","affected_versions":"All"},{"fix":"For development installations, you might need to perform a full install (`pip install .`) before an editable install (`pip install -e .`), or manually link/copy data files into the appropriate locations.","message":"Setuptools' `data_files` (often used for Jupyter configuration files) are not fully supported in editable (`pip install -e .`) mode.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'0.12.3':47 'applic':20 'asset':30 'bug':54 'build':11,36,68 'class':13 'command':12 'current':44 'depend':64 'end':28 'enhanc':58 'extens':22,70 'fix':55 'front':27 'front-end':26 'frontend':69 'function':8 'help':32 'integr':33 'javascript/typescript':29 'jupyt':1,4,19,65 'mainten':56 'packag':2,5,17,41,61,66 'particular':23 'pre':35 'pre-build':34 'process':42 'provid':6 'python':40 'relat':59 'releas':52 'see':51 'setuptool':10,67 'simplifi':15 'standard':62 'step':37 'typic':50 'util':3,7 'version':45","created_at":"2026-04-12T13:59:19.796042+00:00","updated_at":"2026-04-16T15:59:15.068592+00:00","problems":[{"fix":"Ensure `jupyter-packaging` is listed as a build dependency in `pyproject.toml` (`build-system.requires`) or installed in your development environment: `pip install jupyter-packaging`.","cause":"`jupyter-packaging` is typically a build dependency, not a runtime dependency. This error occurs if a package tries to import `jupyter_packaging` directly at runtime, or if it's missing from the build environment during development.","error":"ModuleNotFoundError: No module named 'jupyter_packaging'"},{"fix":"Install Node.js and npm from the official Node.js website or via your system's package manager. Verify installation by running `npm -v` in a new terminal, and ensure the Node.js installation directory is in your system's PATH.","cause":"Jupyter packaging often relies on Node.js and npm (or yarn) to build front-end assets. This error indicates that Node.js and npm are either not installed or not correctly added to your system's PATH environment variable.","error":"'npm' is not recognized as an internal or external command, operable program or batch file"},{"fix":"Install Node.js and npm, and ensure they are accessible in your system's PATH. On Windows, this often means checking the installation options to add to PATH, or manually adding the directory where `node.exe` and `npm.cmd` reside (e.g., `C:\\Program Files\\nodejs\\`). On Linux/macOS, ensure they are installed and your shell can find them.","cause":"This error occurs when `jupyter-packaging` or a Jupyter extension build process attempts to run an npm command (e.g., `npm install`) but cannot find the `node` or `npm` executables, often because they are missing or not in the system's PATH.","error":"ValueError: Please install Node.js and npm before continuing installation."},{"fix":"Install the Rust toolchain (which includes Cargo) by following instructions on `rustup.rs`. Alternatively, if possible, use `conda install` for the package, as `conda-forge` often provides pre-built binaries, or try pinning to an older version of JupyterLab that might not have this dependency or has available wheels.","cause":"When installing some Jupyter-related packages (like JupyterLab or its dependencies) via `pip`, a dependency might require compilation using a Rust toolchain (Cargo) if a pre-built wheel is not available for your specific Python version or operating system. This error means Rust and Cargo are not found.","error":"subprocess-exited-with-error\n× Preparing metadata (pyproject.toml) did not run successfully.\n│ exit code: 1\n╰─> [6 lines of output]\n    Cargo, the Rust package manager, is not installed or is not on PATH. This package requires Rust and Cargo to compile extensions."},{"fix":"For develop mode, you might need to manually copy the `data_files` to their target location or perform a full installation (`pip install .`) instead of an editable one. The `jupyter-packaging` documentation suggests alternatives or workarounds, such as using `include_package_data=True` and `MANIFEST.in` where applicable.","cause":"When creating an editable (develop mode) installation (`pip install -e .`) of a package that uses `jupyter-packaging` to manage `data_files` (e.g., for Jupyter assets), `setuptools` does not properly handle the symlinking or copying of these non-Python files.","error":"data_files are not supported in develop mode (a limitation of setuptools)."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.12.3","cli_name":"","cli_version":null,"type":"library","homepage":"http://jupyter.org","github":"https://github.com/jupyter/jupyter-packaging","docs":null,"changelog":null,"pypi":"https://pypi.org/project/jupyter-packaging/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}