{"id":7600,"library":"pypiserver","title":"pypiserver","description":"pypiserver is a minimal PyPI compatible server for pip or easy_install, designed to serve packages from local directories. It is built on the Bottle web framework and supports uploading wheels, bdists, eggs, and accompanying PGP-signatures via standard Python packaging tools like pip, setuptools, and twine, or simply by copying files. As of version 2.4.1, it is actively maintained with frequent releases, typically several per year, focusing on maintenance, dependency updates, and new features.","status":"active","version":"2.4.1","language":"en","source_language":"en","source_url":"https://github.com/pypiserver/pypiserver","tags":["PyPI server","package index","local packages","development","package management","Python","private registry"],"install":[{"cmd":"pip install pypiserver","lang":"bash","label":"Basic installation"},{"cmd":"pip install pypiserver[passlib,cache]","lang":"bash","label":"With authentication and caching support"}],"dependencies":[{"reason":"Core web framework for the server.","package":"bottle"},{"reason":"Common WSGI server used for deployment.","package":"waitress","optional":true},{"reason":"Asynchronous library for better performance with some WSGI servers.","package":"gevent","optional":true},{"reason":"Required for Apache htpasswd file authentication.","package":"passlib","optional":true},{"reason":"Enables directory caching functionality for improved performance with many packages.","package":"watchdog","optional":true}],"imports":[{"note":"Primarily a command-line tool, but the WSGI application can be imported for custom server setups or embedding. Often used with a WSGI server like Gunicorn: `gunicorn 'pypiserver:app(\"/path/to/packages\")'`.","symbol":"app","correct":"from pypiserver import app"}],"quickstart":{"code":"# 1. Install pypiserver (if not already done)\n# pip install pypiserver\n\n# 2. Create a directory to store your packages\nmkdir -p ~/my_pypi_packages\n\n# 3. Start the PyPI server in the background\n# This will serve packages from ~/my_pypi_packages on port 8080\npypi-server run -p 8080 ~/my_pypi_packages &\n\n# 4. (Optional) Create a dummy package to upload\nmkdir my_dummy_package\necho 'from setuptools import setup, find_packages\\nsetup(name=\"my-dummy-package\", version=\"0.1.0\", packages=find_packages())' > my_dummy_package/setup.py\necho '__init__.py' > my_dummy_package/my_dummy_package/__init__.py\npip install build twine\npython -m build --sdist --wheel my_dummy_package\n\n# 5. Upload a package using twine\n# Replace 'dist/*' with the path to your package files (e.g., .whl, .tar.gz)\ntwine upload --repository-url http://localhost:8080 dist/*\n\n# 6. Install a package from your local PyPI server\n# For HTTP, you might need --trusted-host if pip complains\npip install --index-url http://localhost:8080/simple/ --trusted-host localhost my-dummy-package\n\n# To stop the server later, find its process ID (e.g., `pgrep pypi-server`) and `kill <PID>`","lang":"bash","description":"This quickstart guides you through setting up a basic pypiserver instance, creating a dummy package, uploading it, and then installing it using pip. It demonstrates the command-line interface for running the server and typical client-side interaction."},"warnings":[{"fix":"Upgrade your Python interpreter to version 3.10 or newer, or use an older pypiserver version that supports your Python version if necessary.","message":"Python 3.7 support was removed in v2.4.0. Python 3.6 support was removed in v2.1.0. Ensure your Python environment meets the `>=3.10` requirement.","severity":"breaking","affected_versions":">=2.1.0"},{"fix":"Most modern `pip` and `twine` versions handle SHA256 automatically. Ensure your client tools are up-to-date. If issues persist, consult client tool documentation for hash algorithm compatibility.","message":"The default hashing algorithm for package links switched to SHA256 in v2.0.0. This might affect clients or tools expecting MD5 hashes, though modern tooling generally supports SHA256.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Be aware of these limitations. For documentation, consider alternative hosting solutions or manual distribution. For full PyPI functionality, `pypiserver` might not be suitable.","message":"pypiserver does not implement the full PyPI API. Specifically, documentation uploads are accepted but not saved to disk. Also, advanced features like PEP 708 support are not yet implemented.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `pip install --index-url http://your-server:port/simple/ --trusted-host your-server your-package` or add `extra-index-url = http://your-server:port/simple/` and `trusted-host = your-server` to your `~/.config/pip/pip.conf` (or `~/.pip/pip.conf`).","message":"When serving a local PyPI over HTTP (not HTTPS), `pip` will issue an 'untrusted' warning. You must explicitly add `--trusted-host` to your `pip install` commands or configure it permanently in `pip.conf` or environment variables.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Instead of `pypi-server -r /path/to/packages`, use `pypi-server run /path/to/packages`.","message":"The `--root` option for specifying package directories is deprecated in favor of passing package directories as positional arguments directly to `pypi-server run`.","severity":"deprecated","affected_versions":"All versions (deprecation warning starts at unspecified point)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your virtual environment is activated, or add the Python site-packages script directory to your system's PATH. You can often find the script by `find $(pip env path) -name pypi-server` or `python -m pypiserver run ...` as an alternative.","cause":"The `pypi-server` executable script is not in your system's PATH after installation, or pip installed it in a location not typically on PATH (e.g., a virtual environment's bin/Scripts folder).","error":"pypi-server: command not found"},{"fix":"Verify the package is in the `pypiserver`'s package directory and that the name matches exactly (case-sensitive). Ensure your `pip` client is configured with `--index-url` pointing to your `pypiserver` and `--trusted-host` if using HTTP. Check `pypi-server` logs for 'package not found' entries.","cause":"The package you are trying to install is not present in the directories served by `pypiserver`, or there is a spelling mismatch (case sensitivity), or the client is not configured to look at your local PyPI.","error":"ERROR: Could not find a version that satisfies the requirement <package_name>"},{"fix":"Ensure `pypiserver` is running with a stable WSGI server (e.g., `waitress` or `gunicorn` with appropriate workers). Check server logs for errors or stack traces. Consider enabling caching (`pip install pypiserver[cache]`) for many packages. Monitor system resources (CPU, RAM, file descriptors).","cause":"This can occur due to underlying WSGI server issues (e.g., `gevent` deadlocks), high load, or configuration mismatches. Older `bottle` versions were specifically used in v2.4.0 to mitigate large file upload issues.","error":"Server randomly hangs or becomes unresponsive during uploads/installs."},{"fix":"Ensure the user account running the `pypi-server` process has write permissions to the designated package directory (e.g., `~/my_pypi_packages`). Check `pypi-server` logs for specific error details related to file operations.","cause":"Typically a permissions issue on the package storage directory, preventing `pypiserver` from writing the uploaded files.","error":"500 Internal Server Error during package upload."},{"fix":"Ensure package names match their canonical PyPI spellings. Consider adding commonly misspelled packages manually to your local `pypiserver` index or configure your reverse proxy (if any) to handle common redirects. This is a known limitation when combining local indices with fallback to PyPI mirrors without sophisticated redirect handling.","cause":"The main PyPI (pypi.org) performs 301 redirects for common misspellings (e.g., 'babel' to 'Babel'). When `pypiserver` with a fallback mirror receives a misspelled request, it may redirect to the mirror, which then 404s, leading to an installation failure as the correct spelling is not found.","error":"Installation errors due to PyPI redirects or misspellings when using a fallback PyPI mirror."}]}