Slow GitHub clones, Docker image pulls, and npm or pip installs can look like one network problem, but they use different hosts, protocols, caches, and authentication paths. A Git clone may be waiting on DNS, TLS, or a large repository history; a container pull may be downloading several image layers; a package install may be resolving dependencies or compiling code locally. The quickest fix is to identify which step is slow before changing proxies, mirrors, or client settings.
This guide gives you a repeatable way to diagnose those bottlenecks, choose a suitable workaround, and keep credentials out of logs and configuration files. The goal is not to route every developer tool through the same proxy. It is to improve the slow operation without making builds harder to reproduce or trust.
Identify which part of the workflow is slow
Start by reproducing the problem with one operation at a time. Avoid changing DNS, the VPN route, registry settings, and package-manager configuration all at once: if performance changes, you will not know which change mattered. Note the network you are using, the exact command, the point where it pauses, and whether a retry behaves differently. Compare the same operation on another trusted network if that is practical.
Separate connection setup from data transfer. A long pause before a command prints progress can point to name resolution, a proxy handshake, authentication, or a connection timeout. A transfer that starts promptly but then crawls is more consistent with a constrained route, congestion, packet loss, a busy remote service, or a slow local disk. A package install that downloads quickly but spends time compiling is not necessarily a network issue.
- ✅ Test one small, known public repository or package before retrying a large project.
- ✅ Compare the same command with and without the suspected proxy, where policy permits.
- ✅ Check whether the delay occurs during DNS lookup, connection setup, download, extraction, or compilation.
- ❌ Do not treat a successful browser request as proof that Git, Docker, npm, and pip use the same network path.
- ❌ Avoid repeatedly retrying a failing operation without checking rate limits, authentication, and service status.
For a basic HTTP reachability check on systems with curl, request response headers rather than downloading a large file:
curl -I --connect-timeout 10 https://github.com
curl -I --connect-timeout 10 https://registry-1.docker.io
These checks only establish whether an HTTPS request can reach a host from that shell environment. They do not prove that Git credentials work, that Docker can authenticate to its registry, or that a package manager is using the same proxy settings. If one host responds and another times out, investigate the failing destination and its route instead of applying a broad configuration change.
On Windows, PowerShell’s Test-NetConnection can help distinguish a basic connection problem from an application-level failure. For example, check the relevant host and port, then run the original Git or Docker command to test the full workflow. On macOS and Linux, tools such as nslookup or dig can help inspect DNS results. A DNS response alone does not confirm that the service is reachable or that the returned address is suitable for your network.
Choose a route or proxy that fits the tool
A proxy or VPN can change the network route used to reach a remote service, which may help when the current route is unreliable or blocked by a local network policy. It cannot guarantee that a remote host is available, that a registry is not rate-limiting requests, or that the new route will be faster. Test the specific Git, Docker, or package operation after changing routes; do not judge the result from a general speed test alone.
Also check which process actually makes the connection. Git usually runs in the shell where you invoke it. Docker CLI commands communicate with a Docker daemon, and image downloads are performed by that daemon. Depending on your operating system and Docker setup, the daemon may not inherit proxy variables from your interactive shell. Docker Desktop has its own network and proxy settings; a Linux daemon managed as a system service may require its service-level configuration. If the CLI can contact the daemon but image pulls time out, inspect the daemon’s route and proxy configuration rather than only the shell.
For a VPN, first confirm that the client is connected and that the affected application is included in the active routing mode. Split tunneling, per-app rules, DNS settings, or a second proxy can cause different applications to take different paths. A service such as LeleVPN may be relevant when the route from your current network is the problem, but it is still important to test the actual developer tool and confirm that your organization permits that route.
Use an explicit proxy only when you know its address, trust the operator, and understand which process reads the setting. Proxy environment variables are commonly used by command-line tools:
export HTTPS_PROXY="http://proxy.example:port"
export HTTP_PROXY="http://proxy.example:port"
# Remove the settings from this shell when no longer needed
unset HTTPS_PROXY HTTP_PROXY
The example uses a placeholder, not a working proxy. Do not paste proxy passwords into a command that may be saved in shell history, copied into a ticket, or printed in CI logs. Prefer an approved credential store or a short-lived secret injected by the CI platform. Some tools recognize lowercase variable names as well as uppercase ones, but behavior differs; consult the tool’s documentation and test the exact process that performs the connection.
Keep proxy settings scoped to the smallest necessary context. A temporary shell setting is easier to audit than a global Git configuration if only one build is affected. If you configure a proxy for Git, remove it when it is no longer needed and verify that the URL does not contain a credential. Do not disable TLS certificate verification to work around a certificate error: that can expose source code, tokens, and downloaded packages to interception.
Speed up Git clones and package installs
For Git, first determine whether you need the complete repository history. If you only need the current source tree for a build, a shallow clone can reduce the amount of history transferred:
git clone --depth=1 https://github.com/OWNER/REPOSITORY.git
Replace the placeholders with the repository you are authorized to access. A shallow clone is not a drop-in replacement for a full clone: commands that rely on older commits, tags, merge bases, or complete history may not work as expected. Some CI workflows also need additional history for versioning or change detection. If that applies, use an appropriate fetch depth for the workflow or keep a full clone.
For large repositories, partial clone can defer downloading some file contents until they are needed:
git clone --filter=blob:none https://github.com/OWNER/REPOSITORY.git
This option depends on server support and may cause later Git operations to fetch omitted objects on demand. It is useful only when the checkout workflow can tolerate that behavior. Repositories using Git LFS, submodules, generated assets, or unusual checkout scripts need separate attention: a smaller initial Git transfer does not necessarily make the entire build smaller. Check whether the time is spent cloning Git objects, fetching LFS files, initializing submodules, or checking out files.
For npm, use the project’s lockfile and the matching clean-install command in CI so the dependency tree is predictable. A local cache can reduce repeated downloads, but it does not make an unavailable or unreachable registry reachable. In a CI system, cache the package manager’s supported cache directory using the platform’s protected cache mechanism, and key the cache so that incompatible dependency state is not reused. Do not cache credentials together with package data.
npm ci --prefer-offline
--prefer-offline asks npm to use cached data when available while still allowing missing data to be fetched. It is not a substitute for a correct lockfile, and it does not mean that every package is installed without network access. If a private registry is involved, verify the configured registry and authentication scope without printing the token. A common failure is an install that reaches the public registry but cannot authenticate to the private package host.
For pip, inspect the configured package index and cache behavior before changing mirrors. A trusted organization-managed index may improve access for a distributed team, but an unfamiliar index can serve packages that are not the intended artifacts. Keep the requirements and constraints used by CI under version control, and check whether time is spent downloading wheels or building source distributions locally. A wheel may avoid a local compilation step when one is available for the platform and Python version; it cannot be assumed for every dependency.
Do not delete every cache as a first troubleshooting step. A cache reset can make the next run slower and remove evidence useful for diagnosing a corrupted or stale entry. First identify the package that fails, note the error and configured index, and then clear only the relevant cache if there is a reason to suspect its contents.
Improve Docker pulls without weakening image trust
A Docker image is commonly made up of multiple layers. If a pull pauses, identify whether the delay is before authentication, while fetching a particular layer, or during local extraction. The final step can be limited by disk speed, available storage, or CPU rather than the external connection. Compare a pull of an image already used by your team with a new image, and check whether the same layer is already cached locally.
Registry mirrors can help organizations that repeatedly fetch public images, especially when a trusted mirror is close to their runners. They should be selected and operated deliberately. Check who controls the mirror, how it handles upstream updates, whether it supports the image types and authentication you need, and how your team verifies image provenance. A mirror is not automatically an official source, and changing a registry endpoint should not mean accepting images without review.
Private images add another set of checks. Confirm that the CI identity has permission to pull the requested repository, that the login applies to the registry host being used, and that the secret is not written into a Dockerfile or build log. A successful interactive pull on a developer laptop does not prove that a CI runner has the same credentials or network route. Use the CI platform’s secret-management mechanism and a narrowly scoped identity where available.
For build jobs, reduce unnecessary downloads by using a suitable base image, ordering Dockerfile instructions so that stable dependency layers can be reused, and enabling the build system’s supported cache. Copying frequently changing application files before installing stable dependencies can invalidate more cache than necessary. Conversely, do not preserve a cache so broadly that it hides a required dependency update or leaks files between jobs with different trust levels.
| Operation | Where to investigate | Useful first check | Common caution |
|---|---|---|---|
| Git clone | Shell proxy, repository access, history size, LFS, and submodules | Try a small authorized repository and compare a shallow clone if history is not needed | Shallow history can break workflows that inspect older commits or tags |
| Docker pull | Docker daemon route, registry authentication, layer transfer, and local disk | Check whether the CLI reaches the daemon and inspect which pull stage stalls | Shell proxy variables may not configure the daemon |
| npm install | Registry selection, lockfile, authentication scope, and package cache | Use the project’s clean-install workflow and inspect the failing package host | Do not expose tokens in configuration committed to the repository |
| pip install | Package index, wheel availability, cache, and local compilation | Check whether the delay is during download or building a source package | Use only an index trusted by your organization |
Tune CI for repeatable builds
CI performance improves when jobs avoid transferring the same data unnecessarily and fail with enough detail to identify the cause. Keep the dependency lockfiles and build instructions explicit, then cache only data that can safely be reused. A dependency cache and a Docker layer cache solve different problems; enabling one does not automatically accelerate the other. Use the caching mechanism supported by your CI provider, and check its retention, access controls, and behavior across branches and pull requests.
For Git checkouts, request only the history the job needs. For package installs, prefer the lockfile-driven command used by the project and cache package data rather than generated build outputs whose validity is unclear. For container builds, use cache keys that reflect the relevant base image and dependency inputs. When a cache miss occurs, the job should still be able to build correctly from declared inputs.
Keep credentials out of image layers and source control. Do not put package tokens in a Dockerfile with a normal ARG or ENV instruction, because build arguments and environment values can be retained or exposed through build metadata and logs. Use the builder’s supported secret-mount mechanism where available, and ensure the secret is used only during the step that needs it. Rotate any credential that has been pasted into a public issue, terminal transcript, or unprotected log.
When a CI job times out, inspect the complete log around the first slow or failed request. A later timeout may be a consequence of an earlier request that never completed. Record the host, tool, and stage, but redact tokens, private repository names, and sensitive network details before sharing logs. If a route or mirror improves one job, verify it with a clean run so the result is not simply a warm local cache.
- ✅ Use lockfiles and the same install procedure locally and in CI.
- ✅ Cache package downloads and build layers with the CI platform’s supported controls.
- ✅ Give each job only the registry permissions it needs, and keep secrets out of printed commands.
- ✅ Re-run a clean build to distinguish a real improvement from cached artifacts.
- ❌ Do not disable certificate checks or use an untrusted mirror just to make a timeout disappear.
Troubleshoot timeouts and protect credentials
Use the error message to narrow the failure. A name-resolution error points toward DNS or the configured resolver; a TLS certificate error calls for checking the system clock, certificate chain, inspection proxy, and trust configuration; an authentication error calls for checking the identity and its permissions. A timeout is less specific: it can occur during DNS lookup, connection establishment, TLS negotiation, or a data transfer. Note where the command stopped and compare that with a small request to the same host.
If a proxy is involved, confirm whether it expects HTTP proxying, a SOCKS connection, or a particular authentication method. Do not assume that a browser’s proxy setting is shared with Git, Docker Desktop, a system Docker daemon, npm, and pip. Check each tool’s effective configuration and remove stale settings that point to an unavailable host. When testing a direct route, make the change temporary and restore the approved configuration afterward.
Take care with configuration output. Commands that display environment variables, Git settings, package-manager configuration, or CI context may reveal credentials. Before attaching output to a support request, replace tokens, passwords, private hostnames, and internal repository paths with placeholders. Never publish a subscription URL, access token, registry password, or private key in a diagnostic report.
Finally, make one change at a time and record what changed. If a shallow clone helps but a Docker pull still times out, keep the Git optimization and continue investigating the daemon’s network path. If a trusted mirror helps a team but a local package build remains slow, investigate local compilation rather than changing the registry again. This method keeps the fix narrow, easier to reverse, and safer for the rest of the development workflow.